Policy¶

Dochazka is configurable in a number of ways. Some configuration parameters are set once at installation time and, once set, can never be changed -- these are referred to as "site policy" parameters. Others, referred to as "site configuration parameters" or "site params", are set in configuration files such as "Dochazka_SiteConfig.pm" (see "SITE CONFIGURATION") and can be changed more-or-less at will.

The key difference between site policy and site configuration is that site policy parameters cannot be changed, because changing them would compromise the referential integrity of the underlying database.

Site policy parameters are set at installation time and are stored, as a single JSON string, in the "Policy" table. This table is rendered effectively immutable by a trigger.

For details, see App::Dochazka::REST::Model::Policy.

Employee¶

Users of Dochazka are referred to as "employees" regardless of their legal status -- in reality they might be independent contractors, or students, or even household pets, but as far as Dochazka is concerned they are employees. You could say that "employee" is the Dochazka term for "user".

The purpose of the Employee table/object is to store whatever data the site is accustomed to use to identify its employees.

Within Dochazka itself, employees are distinguished by an internal employee ID number (EID), which is assigned by Dochazka itself when the employee record is created. In addition, four other fields/properties are provided to identify the employee:

• nick
• sec_id
• fullname
• email

All four of these, plus the "eid" field, have "UNIQUE" constraints defined at the database level, meaning that duplicate entries are not permitted. However, of the four, only "nick" is required.

Depending on how authentication is set up, employee passwords may also be stored in this table, using the "passhash" and "salt" fields.

For details, see App::Dochazka::REST::Model::Employee.

Privhistory¶

Dochazka has four privilege levels: "admin", "active", "inactive", and "passerby":

• "admin" -- employee can view, modify, and place/remove locks on her own attendance data as well as that of other employees; she can also administer employee accounts and set privilege levels of other employees
• "active" -- employee can view her own profile, attendance data, modify her own unlocked attendance data, and place locks on her attendance data
• "inactive" -- employee can view her own profile and attendance data
• "passerby" -- employee can view her own profile

Dochazka's "privhistory" object is used to track changes in an employee's privilege level over time. Each time an employee's privilege level changes, a Dochazka administrator (i.e., an employee whose current privilege level is 'admin'), a record is inserted into the database (in the "privhistory" table). Ordinary employees (i.e. those whose current privilege level is 'active') can read their own privhistory.

Thus, with Dochazka it is possible not only to determine not only an employee's current privilege level, but also to view "privilege histories" and to determine employees' privilege levels for any date (timestamp) in the past.

For details, see App::Dochazka::REST::Model::Privhistory and "When history changes take effect".

Schedule¶

In addition to actual attendance data, Dochazka sites may need to store schedules. Dochazka defines the term "schedule" as a series of non-overlapping "time intervals" (or "timestamp ranges" in PostgreSQL terminology) falling within a single week. These time intervals express the times when the employee is "expected" or "supposed" to work (or be "at work") during the scheduling period.

Example: employee "Barb" is on a weekly schedule. That means her scheduling period is "weekly" and her schedule is an array of non-overlapping time intervals, all falling within a single week.

In its current form, Dochazka is only capable of handling weekly schedules only. Some sites, such as hospitals, nuclear power plants, fire departments, and the like, might have employees on more complicated schedules such as "one week on, one week off", alternating day and night shifts, "on call" duty, etc.

Dochazka can still be used to track attendance of such employees, but if their work schedule cannot be expressed as a series of non-overlapping time intervals contained within a contiguous 168-hour period (i.e. one week), then their Dochazka schedule should be set to NULL.

For details, see App::Dochazka::REST::Model::Schedule.

Schedhistory¶

The "schedhistory" table contains a historical record of changes in the employee's schedule. This makes it possible to determine an employee's schedule for any date (timestamp) in the past, as well as (crucially) the employee's current schedule.

Every time an employee's schedule is to change, a Dochazka administrator must insert a record into this table. (Employees who are not administrators can only read their own history; they do not have write privileges.) For more information on privileges, see "AUTHORIZATION".

For details, see App::Dochazka::REST::Model::Schedhistory.

Activity¶

While on the job, employees "work" -- i.e., they engage in various activities that are tracked using Dochazka. The "activities" table contains definitions of all the possible activities that may be entered in the "intervals" table.

The initial set of activities is defined in the site install configuration ("DOCHAZKA_ACTIVITY_DEFINITIONS") and enters the database at installation time. Additional activities can be added later (by administrators), but activities can be deleted only if no intervals refer to them.

Each activity has a code, or short name (e.g., "WORK") -- which is the primary way of referring to the activity -- as well as an optional long description. Activity codes must be all upper-case.

For details, see App::Dochazka::REST::Model::Activity.

Interval¶

Intervals are the heart of Dochazka's attendance data. For Dochazka, an interval is an amount of time that an employee spends doing an activity. In the database, intervals are represented using the "tsrange" range operator introduced in PostgreSQL 9.2.

Optionally, an interval can have a "long_desc" (employee's description of what she did during the interval) and a "remark" (admin remark).

For details, see App::Dochazka::REST::Model::Interval.

Lock¶

In Dochazka, a "lock" is a record in the "locks" table specifying that a particular user's attendance data (i.e. activity intervals) for a given period (tsrange) cannot be changed. That means, for intervals in the locked tsrange:

• existing intervals cannot be updated or deleted
• no new intervals can be inserted

Employees can create locks (i.e., insert records into the locks table) on their own EID, but they cannot delete or update those locks (or any others). Administrators can insert, update, or delete locks at will.

How the lock is used will differ from site to site, and some sites may not even use locking at all. The typical use case would be to lock all the employee's attendance data within the given period as part of pre-payroll processing. For example, the Dochazka client application may be set up to enable reports to be generated only on fully locked periods.

"Fully locked" means either that a single lock record has been inserted covering the entire period, or that the entire period is covered by multiple locks.

Any attempts (even by administrators) to enter activity intervals that intersect an existing lock will result in an error.

Clients can of course make it easy for the employee to lock entire blocks of time (weeks, months, years . . .) at once, if that is deemed expedient.

For details, see App::Dochazka::REST::Model::Lock.

Component¶

Reports are generated from Mason <https://metacpan.org/pod/Mason> templates which consist of components. Mason expects these components to be stored in text files under a directory called the "component root". For the purposes of Dochazka, the component root is created under the Dochazka state directory, which is determined from the "DOCHAZKA_STATE_DIR" site parameter (defaults to "/var/lib/dochazka"). When the server starts, this Mason state in the filesystem is wiped and re-created from the database. The "Component" class is used to manipulate Mason components.

This rather complicated setup is designed to enable administrators to develop their own report templates.

init_timepiece¶

(Re-)initialize the date/time-related package variables