/ 
App-Dochazka-REST-0.080
River stage zero No dependents
/ App::Dochazka::REST::Model::Privhistory

NAME

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

VERSION

Version 0.080

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:

For basic privhistory workflow, see t/005-privhistory.t.

EXPORTS

This module provides the following exports:

get_privhistory

METHODS

spawn

Constructor. See Employee.pm->spawn for general comments.

reset

Instance method. Resets object, either to its primal state (no arguments) or to the state given in PARAMHASH.

Accessor methods

Basic accessor methods for all the fields of privhistory table. These functions return whatever value happens to be associated with the object, with no guarantee that it matches the database.

phid

Accessor method.

eid

Accessor method.

priv

Accessor method.

effective

Accessor method.

remark

Accessor method.

load

Instance method. Loads the privhistory record determining an employee's privilege level at a given point in time. Takes an EID, and, optionally, a timestamp. If no timestamp is given, it defaults to "now". A single privhistory record is loaded into the object, rewriting whatever was there before. Returns a status object: 'OK' means "record fetched", 'WARN' means "query succeeded, but no record fetched", and 'ERR' means "DBI error".

load_by_phid

Instance method. Loads a privhistory record by its 'phid'. General behavior is the same as for the 'load' method, above.

_load

Instance method. Loads a single privhistory record based on the SQL statement and bind parameters given in the arguments.

insert

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

update

There is no 'update' method for privhistory records. Instead, delete and re-recreate.

delete

Instance method. Deletes the record. Returns status object.

FUNCTIONS

get_privhistory

Given a database handle, an ACLEID, an EID, and an optional tsrange, return the history of privilege level changes for that employee over the given tsrange, or the entire history if no tsrange is supplied. Returns a status object where the payload is 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>