The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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:

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 passerby

noof_employees_by_priv

Get number of employees. Argument can be one of the following:

    total admin active inactive passerby

get_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>