NAME
App::Dochazka::REST::Model::Employee - Employee data model
SYNOPSIS
Employee data model
use App::Dochazka::REST::Model::Employee;
...DESCRIPTION
A description of the employee data model follows.
Employees in the database
At the database level, App::Dochazka::REST needs to be able to distinguish one employee from another. This is accomplished by the EID. All the other fields in the employees table are optional.
The employees database table is defined as follows:
CREATE TABLE IF NOT EXISTS employees (
eid serial PRIMARY KEY,
nick varchar(32) UNIQUE NOT NULL,
sec_id varchar(64) UNIQUE,
fullname varchar(96) UNIQUE,
email text UNIQUE,
passhash text,
salt text,
supervisor integer REFERENCES employees (eid),
remark text,
CONSTRAINT kosher_nick CHECK (nick ~* '^[[:alnum:]_][[:alnum:]_-]+$')
)EID
The Employee ID (EID) is Dochazka's principal means of identifying an employee. At the site, employees will be known by other means, like their full name, their username, their user ID, etc. But these can and will change from time to time. The EID should never, ever change.
nick
The idea behind the nick field is that each employee can have an easy-to-remember nickname - ideally something that appeals to them, personally. The nick is required and can only contain certain characters (alphanumerics, underscore, hyphen).
sec_id
The secondary ID is an optional unique string identifying the employee. This could be useful at sites where employees already have a nick (username) and a numeric ID, for example. This gives administrators and supervisors the ability to look up employees by their numeric ID as well as their username (nick).
fullname, email
These fields are optional. If they have a value, it must be unique. value. Dochazka does not check if the email address is valid.
Depending on how App::Dochazka::REST is configured (see especially the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter), these fields may be read-only for employees (changeable by admins only), or the employee may be allowed to maintain their own information.
passhash, salt
The optional passhash and salt fields are designed to hold a hashed password and random salt. See "AUTHENTICATION AND SESSION MANAGEMENT" in App::Dochazka::REST::Guide for details.
supervisor
If the employee has a supervisor who will use Dochazka to monitor the employee's attendance, and provided that supervisor has an EID, this field can be used to set up the relationship.
remark
This field can be used by administrators for any purpose. Ordinarily, the employee herself is not permitted to edit or even display it.
Employees in the Perl API
Individual employees are represented by "employee objects". All methods and functions for manipulating these objects are contained in App::Dochazka::REST::Model::Employee. The most important methods are:
constructor (spawn)
basic accessors (eid, sec_id, nick, fullname, email, passhash, salt, remark)
priv (privilege "accessor" - but privilege info is not stored in the object)
schedule (schedule "accessor" - but schedule info is not stored in the object)
reset (recycles an existing object by setting it to desired state)
insert (inserts object into database)
update (updates database to match the object)
delete (deletes record from database if nothing references it)
load_by_eid (loads a single employee into the object)
load_by_nick (loads a single employee into the object)
team_nicks (returns list of nicks of employees whose supervisor is this employee)
App::Dochazka::REST::Model::Employee also exports some convenience functions:
nick_exists (given a nick, return true/false)
eid_exists (given an EID, return true/false)
list_employees_by_priv (given a priv level, return hash of employees with that priv level)
noof_employees_by_priv (given a priv level, return number of employees with that priv level)
For basic employee object workflow, see the unit tests in t/model/employee.t.
EXPORTS
This module provides the following exports:
- autocreate_employee - function
- eid_exists - function
- get_all_sync_employees - function
- list_employees_by_priv - function
- nick_exists - function
- noof_employees_by_priv - function
METHODS
The following functions expect to be called as methods on an employee object.
The standard way to create an object containing an existing employee is to use 'load_by_eid' or 'load_by_nick':
my $status = App::Dochazka::REST::Model::Employee->load_by_nick( 'georg' );
return $status unless $status->ok;
my $georg = $status->payload;
$georg->remark( 'Likes to fly kites' );
$status = $georg->update;
return $status unless $status->ok;... and the like. To insert a new employee, do something like this:
my $friedrich = App::Dochazka::REST::Model::Employee->spawn( nick => 'friedrich' );
my $status = $friedrich->insert;
return $status unless $status->ok;priv
Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::priv_by_eid N.B.: for this method to work, the 'eid' attribute must be populated
schedule
Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::schedule_by_eid N.B.: for this method to work, the 'eid' attribute must be populated
insert
Instance method. Takes the object, as it is, and attempts to insert it into the database. On success, overwrites object attributes with field values actually inserted. Returns a status object.
update
Instance method. Assuming that the object has been prepared, i.e. the EID corresponds to the employee to be updated and the attributes have been changed as desired, this function runs the actual UPDATE, hopefully bringing the database into line with the object. Overwrites all the object's attributes with the values actually written to the database. Returns status object.
delete
Instance method. Assuming the EID really corresponds to the employee to be deleted, this method will execute the DELETE statement in the database. It won't succeed if there are any records anywhere in the database that point to this EID. Returns a status object.
ldap_sync
Sync the mapping fields to the values found in the LDAP database.
load_by_eid
Analogous method to "load_by_aid" in App::Dochazka::REST::Model::Activity.
load_by_nick
Analogous method to "load_by_aid" in App::Dochazka::REST::Model::Activity.
load_by_sec_id
Analogous method to "load_by_aid" in App::Dochazka::REST::Model::Activity.
FIXME: add unit tests
priv_change_during_range
Given a DBIx::Connector object and a tsrange, returns a non-negative integer value signifying the number of times the employee's priv level changed during the given range.
privhistory_at_timestamp
Given a DBIx::Connector object and a string that must be a timestamp (or a tsrange), returns an App::Dochazka::REST::Model::Privhistory object containing the privhistory record applicable to the employee as of the timestamp (or the lower bound of the tsrange). If there is no such record, the object's properties will be undefined.
NOTE: be careful that the argument really is a valid timestamp or tsrange. If it isn't valid, the DBD::Pg error will be logged and the return value will be undef (not a App::Dochazka::REST::Model::Schedhistory object whose properties are set to undef).
schedule_change_during_range
Given a DBIx::Connector object and a tsrange, returns a non-negative integer value signifying the number of times the employee's schedule changed during the given range.
schedhistory_at_timestamp
Given a DBIx::Connector object and a string that must be a timestamp (or a tsrange), returns an App::Dochazka::REST::Model::Schedhistory object containing the history record applicable to the employee as of the timestamp (or the lower bound of the tsrange). If there is no such record, the object's properties will be undefined.
NOTE: be careful that the argument really is a valid timestamp or tsrange. If it isn't valid, the DBD::Pg error will be logged and the return value will be undef (not a App::Dochazka::REST::Model::Schedhistory object whose properties are set to undef).
team_nicks
Given a DBIx::Connector object, return a status object that, if successful, will contain in the payload a list of employees whose supervisor is the employee corresponding to $self.
has_reports
Given a DBIx::Connector object, return a status object that, if successful, will contain in the payload an integer indicating how many "reports" the employee has - i.e. how many employees, if any, there are whose supervisor is the employee corresponding to $self.
FUNCTIONS
The following functions are not object methods.
EXPORTED FUNCTIONS
The following functions are exported and are not called as methods.
autocreate_employee
Takes a DBIx::Connector object and a nick - the nick is assumed not to exist in the Dochazka employees table. If DOCHAZKA_LDAP_AUTOCREATE is true, attempts to create the employee. Returns a status object.
nick_exists
See exists routine in App::Dochazka::REST::Model::Shared
eid_exists
See exists routine in App::Dochazka::REST::Model::Shared
list_employees_by_priv
Get employee nicks. Argument can be one of the following:
all admin active inactive passerbynoof_employees_by_priv
Get number of employees. Argument can be one of the following:
total admin active inactive passerbyget_all_sync_employees
Function returns a status object. If the status is OK, the payload will contain a reference to an array of employee objects whose sync property is true.
AUTHOR
Nathan Cutler, <presnypreklad@gmail.com>