NAME
App::Dochazka::REST::Model::Interval - activity intervals data model
SYNOPSIS
use App::Dochazka::REST::Model::Interval;
...DESCRIPTION
A description of the activity interval data model follows.
Intervals in the database
Activity intervals are stored in the intervals database table, which has the following structure:
CREATE TABLE intervals (
iid serial PRIMARY KEY,
eid integer REFERENCES employees (eid) NOT NULL,
aid integer REFERENCES activities (aid) NOT NULL,
intvl tsrange NOT NULL,
long_desc text,
remark text,
EXCLUDE USING gist (eid WITH =, intvl WITH &&)
);Note the use of the tsrange operator introduced in PostgreSQL 9.2.
In addition to the Interval ID (iid), which is assigned by PostgreSQL, the Employee ID (eid), and the Activity ID (aid), which are provided by the client, an interval can optionally have a long description (long_desc), which is the employee's description of what she did during the interval, and an admin remark (remark).
Intervals in the Perl API
In the data model, individual activity intervals (records in the intervals table) are represented by "interval objects". All methods and functions for manipulating these objects are contained in this module. The most important methods are:
constructor (spawn)
reset (recycles an existing object by setting it to desired state)
insert (inserts object into database)
delete (deletes object from database)
For basic activity interval workflow, see t/model/interval.t.
EXPORTS
This module provides the following exports:
METHODS
load_by_iid
Boilerplate.
insert
Instance method. Attempts to INSERT a record. Field values are taken from the object. Returns a status object.
update
Instance method. Attempts to UPDATE a record. Field values are taken from the object. Returns a status object.
delete
Instance method. Attempts to DELETE a record. Field values are taken from the object. Returns a status object.
FUNCTIONS
iid_exists
Boolean function
fetch_intervals_by_eid_and_tsrange_inclusive
Given a DBIx::Connector object, an EID and a tsrange, fetch all that employee's intervals that overlap (have at least one point in common with) that tsrange.
Returns a status object. If status level is OK, the payload contains at least one interval. If the status level is NOTICE, it means the operation completed successfully and no overlapping intervals were found.
fetch_intervals_by_eid_and_tsrange
Given a DBIx::Connector object, an EID and a tsrange, return all that employee's intervals that fall within that tsrange. Partial intervals are marked as such (using the partial property).
Before any records are returned, the tsrange is checked to see if it overlaps with any privlevel or schedule changes - in which case an error is returned. This is so interval report-generators do not have to handle changes in employee status.
delete_intervals_by_eid_and_tsrange
Given an EID and a tsrange, delete all that employee's intervals that fall within that tsrange.
Returns a status object.
generate_interval_summary
Given DBIx::Connector object, EID, and tsrange, generate a hash keyed on dates (YYYY-MM-DD) in the range. The value of each key/date is another hash keyed on activity codes. For each activity code the value is the total number of hours spent by the employee doing that activity on the day in question.
The interval must start and end on a day boundary (i.e. 00:00 or 24:00) and partial intervals are treated the same as whole intervals.
AUTHOR
Nathan Cutler, <presnypreklad@gmail.com>