view release on metacpan or  search on metacpan

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

use C<PUT /> (or C<PUT /help>), etc.

Only accessible resources are displayed. For example, a passerby employee will
not see admin resources. A few resources (e.g. C<activity/aid/:aid>), have
different ACL profiles depending on which HTTP method is used.

=head3 Retrieve one's own employee profile

Using C<GET employee/self>, any employee can view her own employee profile.
The payload is a valid employee object.

Alternatively, C<GET employee/self/full> can be used, in which case the
employee's current privilege level and schedule are returned along with the
employee object.

=head3 Retrieve one's own current schedule/privlevel

Using C<GET /priv/self/?:ts> and C<GET /schedule/self/?:ts>, any employee 
can retrieve her own current privlevel and schedule. By including a timestamp
she can also retrieve her privlevel and schedule as of any arbitrary date/time.

=head3 Generate reports

Passerby employees can use the C<POST genreport> operation to generate
reports from any report templates (Mason components) with ACL profile
'passerby'.


=head2 inactive

The inactive privlevel is intended for employees who are not currently
attending work, but are expected to resume their attendance at some point in
the future: for example, employees on maternity leave, sabbatical, etc.

Short-term leave situations like medical leave can of course be handled by
having the employee enter attendance intervals according to their schedule, but
using a special activity like, for example, 'SICK_LEAVE'. The 'inactive'
privlevel is appropriate if an employee will be inactive for a longer period,
during which she is not expected to fill out attendance.

Though such employees might not be expected to even log in to Dochazka during
their period of inactivity, if they happen to do so they can engage in the
following workflows (in addition to the passerby workflows described in the
previous section).

=head3 Retrieve one's own schedule/privilege history

Employee schedules and privlevels change over time. To ensure that historical
attendance data is always associated with the schedule and privlevel in effect
at the time the attendance took place, all changes to employee schedules and
privlevels are recorded in a "history table". 

Since inactive employees are still employees (or members of the organization),
they are authorized to view (retrieve) their privilege/schedule histories using
the C<schedule/history/self/?:tsrange> and C<priv/history/self/?:tsrange>
resources. 

=head3 Edit one's own employee profile (certain fields)

Inactive employees are authorized to edit certain fields of their employee
profile (e.g., to change their password or correct the spelling of their full
name, etc.). These fields are configurable via the DOCHAZKA_PROFILE_EDITABLE_FIELDS site
parameter.

=head3 Retrieve one's own attendance/lock intervals

Although inactive employees are not authorized to enter new attendance/lock
intervals, they can retrieve their own past intervals, for example by browsing
in the web client, etc.

=head3 Generate reports

Inactive employees can use the C<POST genreport> operation to generate
reports from any report templates (Mason components) with ACL profile
'inactive' or below.


=head2 active

=head3 Add new attendance intervals

Active employees can add new attendance data ("intervals") subject to the
following limitations: 

=over

=item (a) only their own attendance - not that of other employees,

=item (b) attendance interval must not conflict with an existing lock interval,

=item (c) attendance interval must not extend past the end of the current month and, 

=item (d) attendance interval must not overlap with an existing interval.

=back

    Example 1: Employee 'pepik' tries to insert an attendance interval
               [1985-04-27 08:00, 1985-04-27 12:00) but there is a 
	       lock in place for that date. In such a case, the lock would have
               to be removed by an administrator, or 'pepik' would be out of luck.

    Example 2: Today's date is 2014-10-22 and 'pepik' attempts to insert
               an attendance interval [2014-11-07 08:00, 2014-11-07 08:30) -
	       this will not be possible until 2014-11-01..

New attendance data is added via POST requests on C<interval/new>.

=head3 Add new lock intervals

Active employees are authorized to lock attendance data by adding new lock
intervals subject to the following restrictions:

=over

=item (a) only on their own attendance,

=item (b) only on past attendance and up to the end of the current month,

=item (c) lock interval must not overlap with any other lock intervals.

=back