NAME
App::Dochazka::Common - Dochazka Attendance and Time Tracking System shared modules
VERSION
Version 0.210
SYNOPSIS
Sic transit gloria mundi.
DESCRIPTION
This distro contains modules that are used by both the server App::Dochazka::REST and the command-line client App::Dochazka::CLI.
DOCHAZKA DATA MODEL
This section describes the Dochazka data model. Conceptually, Dochazka data can be seen to exist in the following classes of objects, all of which are implemented by this module:
Policy (parameters set when database is first created)
Employee (an individual employee)
Privhistory (history of changes in an employee's privilege level)
Schedule (a schedule)
Schedhistory (history of changes in an employee's schedule)
Activities (what kinds of work are recognized)
Intervals (the "work", or "attendance", itself)
Locks (determining whether a reporting period is locked or not)
Components (Mason components, i.e. report templates)
These classes are described in the following sections.
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 employeesactive-- employee can view her own profile, attendance data, modify her own unlocked attendance data, and place locks on her attendance datainactive-- employee can view her own profile and attendance datapasserby-- 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 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.
PACKAGE VARIABLES AND EXPORTS
FUNCTIONS
init_timepiece
(Re-)initialize the date/time-related package variables