The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Dochazka-REST-0.480
River stage zero No dependents
1 ++
/ App::Dochazka::REST::Model::Employee

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 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,
        remark    text,
        stamp     json
    )

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 nick field is intended to be used for storing the employee's username. While storing each employee's username in the Dochazka database has undeniable advantages, it is not required - how employees are identified is a matter of site policy, and internally Dochazka does not use the nick to identify employees. Should the nick field have a value, however, Dochazka requires that it be unique.

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, and the administrators need to have the ability to look up employees by their numeric ID.

fullname, email

Dochazka does not maintain any history of changes to the employees table.

The full_name and email fields must also be unique if they have a 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 passhash and salt fields are optional. See "AUTHENTICATION" for details.

remark, stamp

# FIXME

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/004-employee.t.

EXPORTS

This module provides the following exports:

nick_exists - function
eid_exists - function
list_employees_by_priv - 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.

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 the employee's privlevel during that range, or NULL if the privlevel changed during the range.

privhistory_at_timestamp

Given a DBIx::Connector object and a string that can be either a timestamp or a tsrange, returns an App::Dochazka::REST::Model::Privhistory object containing the privhistory record applicable to the employee either at the timestamp or at the lower bound of the tsrange. If there is no such record, the object's properties will be undefined.

schedule_change_during_range

Given a DBIx::Connector object and a tsrange, returns true or false value reflecting whether or not the employee's schedule changed during the range.

schedhistory_at_timestamp

Given a DBIx::Connector object and a string that can be either a timestamp or a tsrange, returns an App::Dochazka::REST::Model::Schedhistory object containing the history record applicable to the employee either at the timestamp or at the lower bound of the tsrange. If there is no such record, the object's properties will be undefined.

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.

FUNCTIONS

The following functions are not object methods.

EXPORTED FUNCTIONS

The following functions are exported and are not called as methods.

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

AUTHOR

Nathan Cutler, <presnypreklad@gmail.com>