NAME

App::Dochazka::REST::Model::Privhistory - privilege history functions

SYNOPSIS

    use App::Dochazka::REST::Model::Privhistory;

    ...

DESCRIPTION

A description of the privhistory data model follows.

Privilege levels in the database

Type

The privilege levels themselves are defined in the privilege enumerated type:

    CREATE TYPE privilege AS ENUM ('passerby', 'inactive', 'active',
    'admin')

Table

Employees are associated with privilege levels using a privhistory table:

    CREATE TABLE IF NOT EXISTS privhistory (
        phid       serial PRIMARY KEY,
        eid        integer REFERENCES employees (eid) NOT NULL,
        priv       privilege NOT NULL;
        effective  timestamp NOT NULL,
        remark     text,
        stamp      json
    );

Stored procedures

There are also two stored procedures for determining privilege levels:

• priv_at_timestamp Takes an EID and a timestamp; returns privilege level of that employee as of the timestamp. If the privilege level cannot be determined for the given timestamp, defaults to the lowest privilege level ('passerby').

• current_priv Wrapper for priv_at_timestamp. Takes an EID and returns the current privilege level for that employee.

Privhistory in the Perl API

When an employee object is loaded (assuming the employee exists), the employee's current privilege level and schedule are included in the employee object. No additional object need be created for this. Privhistory objects are created only when an employee's privilege level changes or when an employee's privilege history is to be viewed.

In the data model, individual privhistory records are represented by "privhistory objects". All methods and functions for manipulating these objects are contained in App::Dochazka::REST::Model::Privhistory. The most important methods are:

• constructor (spawn)

• basic accessors (phid, eid, priv, effective, remark)

• reset (recycles an existing object by setting it to desired state)

• load (loads a single privhistory record)

• load_by_phid (wrapper for load_by_id)

• load_by_id (load a single privhistory record by its PHID)

• insert (inserts object into database)

• delete (deletes object from database)

For basic privhistory workflow, see t/model/privhistory.t.

EXPORTS

This module provides the following exports:

phid_exists (boolean)

get_privhistory

METHODS

load_by_eid

Supposed to be a class method, but in reality we just don't care what the first argument is.

load_by_id

Class method.

load_by_phid

Wrapper for load_by_id

insert

Instance method. Attempts to INSERT a record into the 'privhistory' table. Field values are taken from the object. Returns a status object.

update

Instance method. Updates the record. Returns status object.

delete

Instance method. Deletes the record. Returns status object.

FUNCTIONS

phid_exists

Boolean function

get_privhistory

Takes a PARAMHASH which can have one or more of the properties 'eid', 'nick', and 'tsrange'.

At least one of { 'eid', 'nick' } must be specified. If both are specified, the employee is determined according to 'eid'.

The function returns the history of privilege level changes for that employee over the given tsrange, or the entire history if no tsrange is supplied.

The return value will always be an App::CELL::Status object.

Upon success, the payload will contain a 'history' key, the value of which will be a reference to an array of privhistory objects. If nothing is found, the array will be empty. If there is a DBI error, the payload will be undefined.

EXAMPLES

In this section, some examples are presented to help understand how this module is used.

Mr. Moujersky joins the firm

Mr. Moujersky was hired and his first day on the job was 2012-06-04. The privhistory entry for that might be:

    phid       1037 (automatically assigned by PostgreSQL)
    eid        135 (Mr. Moujersky's Dochazka EID)
    priv       'active'
    effective  '2012-06-04 00:00'

Mr. Moujersky becomes an administrator

Effective 2013-01-01, Mr. Moujersky was given the additional responsibility of being a Dochazka administrator for his site.

    phid        1512 (automatically assigned by PostgreSQL)
    eid        135 (Mr. Moujersky's Dochazka EID)
    priv       'admin'
    effective  '2013-01-01 00:00'

Mr. Moujersky goes on parental leave

In February 2014, Mrs. Moujersky gave birth to a baby boy and effective 2014-07-01 Mr. Moujersky went on parental leave to take care of the Moujersky's older child over the summer while his wife takes care of the baby.

    phid        1692 (automatically assigned by PostgreSQL)
    eid        135 (Mr. Moujersky's Dochazka EID)
    priv       'inactive'
    effective  '2014-07-01 00:00'

Note that Dochazka will begin enforcing the new privilege level as of effective, and not before. However, if Dochazka's session management is set up to use LDAP authentication, Mr. Moujersky's access to Dochazka may be revoked at any time at the LDAP level, effectively shutting him out.

AUTHOR

Nathan Cutler, <presnypreklad@gmail.com>

cpanm App::Dochazka::REST

perl -MCPAN -e shell
install App::Dochazka::REST