view release on metacpan or  search on metacpan

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

# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# ************************************************************************* 

package App::Dochazka::REST::Docs::Workflow;

use 5.012;
use strict;
use warnings;


1;
__END__


=head1 NAME

App::Dochazka::REST::Docs::Workflow - Documentation of REST workflow


=head1 DESCRIPTION

This is a POD-only module containing documentation describing standard Dochazka
workflow scenarios and the REST resources used therein.

It is intended to be used in the functional testing process.

=head1 WORKFLOW SCENARIOS

The workflow scenarios are divided into sections according to the privlevel of
the logged-in employee doing the "work" - i.e., interacting with the Dochazka
REST server.

The workflow scenarios are presented in order of increasing privilege.
Employees with higher privilege can perform all the workflow scenarios
available to those of lower privilege.


=head2 passerby

Passerby is the default privlevel. In other words, employees without any
privhistory entries will automatically be assigned this privlevel.

Passerby employees (which need not be "employees" in a legal sense) can engage
in the following workflows:

=head3 Login

If LDAP authentication is enabled and C<DOCHAZKA_LDAP_AUTOCREATE> is set, a new
passerby employee will be created whenever an as-yet unseen employee logs in
(authenticates herself to the REST server). Otherwise, a passerby employee can
log in only if an administrator has created the corresponding employee profile.

=head3 Explore available resources 

Any logged-in employee is free to explore available resources. The starting
point for such exploration can be C<GET /> (i.e. a GET request for the
top-level resource), which is the same as C<GET /help>. The information
returned is specific to the HTTP method used, so for PUT resources one needs to
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