view release on metacpan or  search on metacpan

lib/App/Dochazka/REST/ResourceDefs.pm  view on Meta::CPAN

either not been set or has been set to 'false'.
EOH
    },

    # /schedule/all/disabled
    'schedule/all/disabled' => 
    { 
        parent => 'schedule/all',
        handler => {
            GET => 'handler_schedule_all',
        },
        acl_profile => 'admin', 
        cli => 'schedule all disabled',
        description => 'Retrieves (GET) all schedules (disabled and non-disabled)',
        documentation => <<'EOH',
=pod

This resource returns a list (array) of all schedules, regardless of the contents
of the 'disabled' field.
EOH
    },

    # /schedule/eid/:eid/?:ts
    'schedule/eid/:eid/?:ts' => 
    { 
        parent => 'schedule',
        handler => {
            GET => 'handler_get_schedule_eid',
        },
        acl_profile => 'passerby',
        cli => 'schedule eid $EID [$TIMESTAMP]',
        validations => {
            'eid' => 'Int',
        },
        description => 'Get the current schedule of arbitrary employee, or with optional timestamp, that employee\'s schedule as of that timestamp',
        documentation => <<'EOH',
=pod

This resource retrieves the schedule of an arbitrary employee specified by EID.

If no timestamp is given, the current schedule is retrieved. If a timestamp
is present, the schedule as of that timestamp is retrieved.
EOH
    },

    # /schedule/new
    'schedule/new' => 
    { 
        parent => 'schedule',
        handler => {
            POST => 'handler_schedule_new',
        },
        acl_profile => 'admin', 
        cli => 'schedule new $JSON',
        description => 'Insert schedules',
        documentation => <<'EOH',
=pod

Given a set of intervals, all of which must fall within a single contiguous
168-hour (7-day) period, this resource performs all actions necessary to either
create a new schedule from those intervals or verify that an equivalent
schedule already exists.

Sample JSON:

    { "schedule" : [
        "[2014-09-22 08:00, 2014-09-22 12:00)",
        "[2014-09-22 12:30, 2014-09-22 16:30)",
        "[2014-09-23 08:00, 2014-09-23 12:00)",
        "[2014-09-23 12:30, 2014-09-23 16:30)",
        "[2014-09-24 08:00, 2014-09-24 12:00)",
        "[2014-09-24 12:30, 2014-09-24 16:30)",
        "[2014-09-25 08:00, 2014-09-25 12:00)",
        "[2014-09-25 12:30, 2014-09-25 16:30)"
    ] }

(Optionally, an scode can be assigned by including an "scode" property.)

Read on for details:

First, a set of scratch intervals is created in the 'schedintvls' table.
If this succeeds, an INSERT operation is used to create a new record in the
'schedule' table. This operation has two possible successful outcomes 
depending on whether such a schedule already existed in the database, or not.
The status codes for these outcomes are DISPATCH_SCHEDULE_OK and
DISPATCH_SCHEDULE_INSERT_OK, respectively.

In both cases, the underlying scratch intervals are deleted automatically.
(All operations on the 'schedintlvs' table are supposed to be hidden from 
Dochazka clients.) 

Note that many sets of intervals can map to a single schedule (the conversion
process is only interested in the day of the week), so this resource may return
DISPATCH_SCHEDULE_OK more often than you think.

Whether or not the exact schedule existed already, if the underlying database
operation is successful the payload will contain three properties: 'sid' (the
SID assigned to the schedule containing the intervals), 'intervals' (the
intervals themselves), and 'schedule' (the intervals as they appear after being
converted into the format suitable for insertion into the 'schedule' table).

N.B. At present there is no way to just check for the existence of a schedule
corresponding to a given set of intervals. 
EOH
    },

    # /schedule/nick/:nick/?:ts
    'schedule/nick/:nick/?:ts' => 
    { 
        parent => 'schedule',
        handler => {
            GET => 'handler_get_schedule_nick',
        },
        acl_profile => 'admin', 
        cli => 'schedule nick $NICK [$TIMESTAMP]',
        validations => {
            'nick' => $term_validation,
        },
        description => 'Get the current schedule of arbitrary employee, or with optional timestamp, that employee\'s schedule as of that timestamp',
        documentation => <<'EOH',
=pod