/ 
App-Dochazka-CLI-0.240
River stage zero No dependents
/ App::Dochazka::CLI::Guide

NAME

App::Dochazka::CLI::Guide - Dochazka CLI Guide

VERSION

Version 0.240

CLI COMMANDS

Introduction

The CLI commands can be divided into four categories:

"Commands for generating HTTP requests"
"Commands for Dochazka administrators"
"Commands for Dochazka supervisors"
"Commands for Dochazka users"

Commands for generating HTTP requests

The CLI enables the user to generate HTTP requests to an App::Dochazka::REST server and view the server's responses. Commands in this category -- also known as "REST test" commands -- have a direct correlation with the REST server resources, always starting with one of the four basic HTTP methods supported by the REST server: GET, PUT, POST, DELETE. These commands are useful mainly for Dochazka developers, but may also be used by administrators and normal users -- e.g., for troubleshooting and ad hoc testing, or for doing things that the "normal" commands do not support. A "best effort" has been made to support all the REST resources.

Commands in this category start with the HTTP method and continue with the resource (except it is written with spaces instead of forward slashes) and concludes with the request entity, if any.

All CLI commands must be written on a single line of input, and commands in this category are no exception.

Examples:

DELETE INTERVAL IID 24

The equivalent of DELETE interval/iid/24

POST DOCU TEXT "employee/eid/:eid"

The equivalent of POST docu/text with the request entity shown.

POST EMPLOYEE EID { "eid" : 15, "sec_id" : 340 }

Update the secondary ID of the employee with EID 15.

A full list of REST test commands can be found in the source code of the App::Dochazka::CLI::CommandMap module.

Commands for Dochazka administrators

Dochazka administrators have access to all of Dochazka's resources and can call them directly by generating appropriate HTTP requests. This can be a bit tedious, however, so "real" CLI commands have been implemented for the more commonly used administrative procedures, like changing an employee's privilege level or schedule, removing locks, viewing attendance data entered by employees, etc.

These commands are detailed in the "ADMINISTRATOR WORKFLOWS" section.

Commands for Dochazka supervisors

Supervisors are Dochazka users who, in "real life", are in charge of a group of employees who report to them. The idea here is that the supervisor can view and modify the attendance data and other records of their reports (i.e. of the employees in their team or department). The commands used for this purpose are a subset of the administrator commands.

These commands are detailed in the "SUPERVISOR WORKFLOWS" section.

Commands for Dochazka users

Finally there are the core, day-to-day commands used by Dochazka users (employees of the organization) to enter attendance data, generate reports, etc.

These commands are detailed in the "USER WORKFLOWS" section.

ADMINISTRATOR WORKFLOWS

Activities

View all activities, including disabled

ACTIVITY ALL DISABLED

Displays a list of all activities, including disabled activities.

Add a new activity

From time to time, new activities will need to be added:

PUT activity code $CODE { "long_desc" : "activity description here" }

Optionally, a "remark" property can be included as well.

Disable an activity

To accomplish this, we can use a REST test command:

PUT activity aid $AID { "disabled" : "t" }
PUT activity code $CODE { "disabled" : "t" }

Re-enable an activity

To accomplish this, we can use a REST test command:

PUT activity aid $AID { "disabled" : "f" }
PUT activity code $CODE { "disabled" : "f" }

Delete an activity

Assuming nothing points to it, an activity can be deleted:

DELETE activity aid $AID
DELETE activity code $CODE

Employees

Specify an employee

Wherever it is necessary to specify an employee, the command is shown as

EMPLOYEE_SPEC

This has a special meaning and is not meant to be typed in verbatim. EMPLOYEE_SPEC can be given in any of the following ways:

EMPLOYEE=$NICK
EMPLOYEE=$SEC_ID
EMPLOYEE=$EID

(where $NICK is an employee nick, $SEC_ID is an employee secondary ID, and $EID is an employee ID (EID))

If, for some reason, this does not lead to the desired result, you can force a lookup on a particular property:

NICK=$NICK
SEC_ID=$SEC_ID
EID=$EID

Note that there must not be any whitespace before or after the equal sign.

Get list of employees

Commands to list all employees, or just those with a given privilege level:

EMPLOYEE LIST             # lists all employees
EMPLOYEE LIST admin
EMPLOYEE LIST active
EMPLOYEE LIST inactive
EMPLOYEE LIST passerby

Only nicks are shown, in alphabetical order.

Create a new employee

If you are using LDAP authentication, your employees are in the LDAP database and you can turn on DOCHAZKA_LDAP_AUTOCREATE. Then employees will be created automatically the first time they log in. Alternatively, employees can be created manually:

PUT employee nick $NICK { "fullname" : "King George III" }

In addition to "fullname", the following properties can be specified inside the curly brackets:

sec_id
email
password
remark

For example, to add an employee with nick 'nancy' the command might look like this:

 PUT employee nick nancy { "fullname" : "Nancy Bright Red", "email" : "nancy@identity.org" }

The new employee will have passerby privileges only until a privhistory record is created (see "Add privilege history record", below).

Set employee secondary ID

To manually change an employee's secondary ID, do one of the following:

EMPLOYEE_SPEC SEC_ID $SEC_ID
EMPLOYEE_SPEC SET SEC_ID $SEC_ID

Example:

EMPLOYEE=joe SET SEC_ID 4553

Set employee full name

To manually change an employee's full name, do one of the following:

EMPLOYEE_SPEC FULLNAME $WHATEVER
EMPLOYEE_SPEC SET FULLNAME $WHATEVER

Examples:

EMPLOYEE=baird FULLNAME Joseph Baird
EMPLOYEE=baird FULLNAME JUDr. Joseph Peacock Baird LLM, Esq.

Do not use any quotes in or around the full name.

Set employee password

To manually change an employee's password, do:

EMPLOYEE_SPEC PASSWORD
EMPLOYEE_SPEC SET PASSWORD

You will be asked to type in the new password twice. This updates the password that Dochazka stores in the 'employees' table. Whether this has any effect on the user's ability to log in depends on what authentication method is being used and where the passwords for that method are stored.

Schedules

View all schedules (including disabled schedules)

All existing schedules can be dumped to the screen:

SCHEDULES FETCH ALL

Note that this does not include disabled schedules. To include those in the listing, use this command:

SCHEDULES FETCH ALL DISABLED

View an individual schedule (by SID or SCODE)

If the SID or SCODE of a schedule is known, it can be looked up like so:

SID=12 SHOW
SCODE=SAMPLE SHOW

The first example looks up the schedule with SID 12, and the second looks up the schedule with SCODE "SAMPLE".

Define a new schedule

The following commands can be used to "create" a schedule, i.e. define it and save it in the database. The idea is to first build up the schedule in memory and then, when this "working" schedule is complete, submit it to the REST server.

View working schedule

To see the current state of the working schedule, do:

SCHEDULE DUMP
SCHEDULE MEMORY

Add a line to the working schedule

Each line of the working schedule corresponds to a time interval. Time intervals are defined by specifying when they begin and end. Ordinarily, this format should be sufficient:

SCHEDULE MON 8:00-12:00

(This sets up a time interval that begins on Monday 8:00 a.m. and ends at 12:00 noon that same day.)

This method might not work if the interval starts and ends on different days - in which case we would use a different format:

SCHEDULE MON 23:00 TUE 03:30
SCHEDULE MON 23:00 - TUE 03:30

Note that it is possible for the working schedule to contain overlapping or otherwise nonsensical intervals.

Quickly add identical intervals MON-FRI

If your schedule has the same intervals for all five days of the standard work week (Monday through Friday), the process of defining the schedule can be accelerated by using the keyword ALL instead of MON, TUE, WED, etc.

SCHEDULE ALL 8:00-12:00
SCHEDULE ALL 12:30-16:30

Example:

Dochazka(2015-04-08) root ADMIN> schedule all 8:00-12:00 [ MON 08:00, MON 12:00 ) [ TUE 08:00, TUE 12:00 ) [ WED 08:00, WED 12:00 ) [ THU 08:00, THU 12:00 ) [ FRI 08:00, FRI 12:00 )

Dochazka(2015-04-08) root ADMIN> schedule all 12:30-16:30 [ MON 08:00, MON 12:00 ) [ MON 12:30, MON 16:30 ) [ TUE 08:00, TUE 12:00 ) [ TUE 12:30, TUE 16:30 ) [ WED 08:00, WED 12:00 ) [ WED 12:30, WED 16:30 ) [ THU 08:00, THU 12:00 ) [ THU 12:30, THU 16:30 ) [ FRI 08:00, FRI 12:00 ) [ FRI 12:30, FRI 16:30 )

Add an scode to the working schedule

Schedules are distinguished from eachother by their Schedule ID (SID) and by their code (scode). To associate an scode with the working schedule, do this:

SCHEDULE SCODE $SCODE

Example:

SCHEDULE SCODE 9_TO_5

The scode may not contain whitespace.

Submit working schedule to REST server

Once you are satisfied with your working schedule, submit it to the REST server like this:

SCHEDULE NEW

This is the "moment of truth" when you find out if the schedule is "kosher" enough to make it into the database.

Example with overlapping intervals:

Dochazka(2015-04-08) root ADMIN> schedule memory
[ MON 23:00, TUE 03:30 )
[ MON 23:00, TUE 03:40 )

Dochazka(2015-04-08) root ADMIN> schedule new
*** Anomaly detected ***
Status:      500 Internal Server Error
ERR: DBI reports DBD::Pg::st execute failed: ERROR:  conflicting key value violates
exclusion constraint "schedintvls_ssid_intvl_excl"DETAIL:  Key (ssid, intvl)=(11,
["2015-03-23 23:00:00+01","2015-03-24 03:40:00+01")) conflicts with existing key
(ssid, intvl)=(11, ["2015-03-23 23:00:00+01","2015-03-24 03:30:00+01")). at
/usr/lib/perl5/site_perl/5.20.1/App/Dochazka/REST/Model/Schedintvls.pm line 183.

Clear the working schedule

The working schedule can be cleared:

SCHEDULE CLEAR

Add a remark to a schedule

Once you manage to get a schedule into the database, you can add a remark to it:

SCHEDULE_SPEC REMARK $REMARK
SCHEDULE_SPEC SET REMARK $REMARK

The remark can contain whitespace, but should not contain any quotation marks. The same command can be used to change an existing remark. To delete an existing remark, leave out $REMARK.

Set or modify scode

Once you manage to get a schedule into the database, you can set or modify its scode:

SCHEDULE_SPEC SCODE $REMARK
SCHEDULE_SPEC SET SCODE $REMARK

The scode may contain only ASCII letters, numerals, underscores, and hyphens.

Disable a schedule

Assuming we know the SID or scode of the schedule, we can disable it:

PUT SCHEDULE SID $SID { "disabled" : "t" }
PUT SCHEDULE SCODE $SCODE { "disabled" : "t" }

Re-enable a schedule

To re-enable a disabled schedule:

PUT SCHEDULE SID $SID { "disabled" : "f" }
PUT SCHEDULE SCODE $SCODE { "disabled" : "f" }

Histories

Maintaining/updating employee history records (recording changes in privilege level and schedule, primarily) is a typical administrator workflow.

Add privilege history record

EMPLOYEE_SPEC PRIV_SPEC _TIMESTAMP
EMPLOYEE_SPEC SET PRIV_SPEC _TIMESTAMP
EMPLOYEE_SPEC PRIV_SPEC EFFECTIVE _TIMESTAMP
EMPLOYEE_SPEC SET PRIV_SPEC EFFECTIVE _TIMESTAMP

(In other words, the SET and EFFECTIVE keywords can be omitted.)

Examples:

Employee joe becomes an active employee as of 2015-06-30 00:00:

EMPLOYEE=joe active 2015-06-30

The employee with secondary ID 634 becomes a passerby as of 1958-04-27

SEC_ID=634 passerby EFFECTIVE 1958-04-27

Add schedule history record

EMPLOYEE_SPEC SCHEDULE_SPEC _TIMESTAMP
EMPLOYEE_SPEC SET SCHEDULE_SPEC _TIMESTAMP
EMPLOYEE_SPEC SCHEDULE_SPEC EFFECTIVE _TIMESTAMP
EMPLOYEE_SPEC SET SCHEDULE_SPEC EFFECTIVE _TIMESTAMP

(In other words, the SET and EFFECTIVE keywords can be omitted.)

Examples:

Employee joe goes on schedule KOBOLD as of 2015-06-30 00:00:

EMPLOYEE=joe scode=KOBOLD 2015-06-30

The employee with secondary ID 634 goes on the schedule with SID 32 as of 1958-04-27

SEC_ID=634 SET SID=32 EFFECTIVE 1958-04-27

Add remark to history record

Privilege and schedule history records can have remarks associated with them, which can be a handy way to remember why the privelege/schedule took place. The first column of the history listing:

EMPL=joe PRIV HISTORY

is either PHID (Privilege History ID) or SHID (Schedule History ID). To add a remark to PHID 352, do the following:

PHID=352 REMARK Employee fired by Big Bad Boss

For schedule history remarks, do this:

SHID=652 REMARK Employee goes onto a different schedule

or, in general:

PHISTORY_SPEC [SET] REMARK $REMARK
SHISTORY_SPEC [SET] REMARK $REMARK

SUPERVISOR WORKFLOWS

Employees

View profile of an employee in my team

Assuming the employee really is in your team, you can do any of the following:

EMPLOYEE_SPEC
EMPLOYEE_SPEC PROFILE
EMPLOYEE_SPEC SHOW

For the meaning of EMPLOYEE_SPEC, see "Specifying an employee", above.

For example, to view the profile of team member joe, just type:

EMPLOYEE=joe

or

EMPLOYEE=joe PROFILE

Privilege levels

View an employee's privilege level

Although EMPLOYEE_SPEC PROFILE shows the employee's privilege level, there is also a dedicated command:

EMPLOYEE_SPEC PRIV

Schedules

View an employee's schedule

Provided the employee has a schedule defined, it can be displayed by typing:

EMPLOYEE_SPEC SCHEDULE

Histories

For each employee, Dochazka maintains two "histories": privilege history and schedule history. Each time an employee's privilege or schedule status changes, a history record should be added.

View an employee's privilege history

EMPLOYEE_SPEC PRIV HISTORY

View an employee's schedule history

EMPLOYEE_SPEC SCHEDULE HISTORY

USER WORKFLOWS

Activities

View a list of all activities

To view a list of all activities, do:

ACTIVITIES
ACTIVITIES ALL

Employees

View own employee profile

Each Dochazka employee has a "profile" with some basic information. One's own profile can be viewed by doing any of the following:

EMPLOYEE
EMPLOYEE PROFILE
EMPLOYEE SHOW

Set own password

To manually change your password, do:

EMPLOYEE PASSWORD
EMPLOYEE SET PASSWORD

You will be asked to type in the new password twice. If you still can't log in after doing this, contact your local Dochazka administrator.

Privilege levels

View one's own privilege level

Although EMPLOYEE PROFILE shows the employee's privilege level, there is also a dedicated command:

PRIV

Example

Dochazka(2015-04-08) demo PASSERBY> priv
The current privilege level of demo (EID 2) is passerby

Schedules

View one's own schedule

Provided the employee has a schedule defined, it can be displayed by typing:

SCHEDULE

Display an arbitrary schedule

Histories

View own privilege history

PRIV HISTORY

View own schedule history

SCHEDULE HISTORY

Intervals

Enter an interval

"Canonical" form

The canonical way to enter an attendance interval:

INTERVAL $TIME_BEGIN $TIME_END $ACTIVITY_CODE $DESCRIPTION
INTERVAL $TIME_BEGIN - $TIME_END $ACTIVITY_CODE $DESCRIPTION

Use the above command variant if you need to enter the date along with the time, or if the interval begins and ends on a different date. Example:

INTERVAL 2015-04-27 08:00 - 2015-04-27 12:00 WORK Prepare notes for meeting

If the date is omitted, the "prompt date" will be used:

INTERVAL 08:00 - 12:00 WORK Prepare notes for meeting

If a beginning date is specified, but no ending date, the beginning date will be applied to the end as well:

INTERVAL 2015-04-28 12:30 - 16:30 WORK Wait for Godot

Time range

Another way to omit the date (default to the prompt date) is to enter a time range:

INTERVAL $TIME_RANGE $ACTIVITY_CODE $DESCRIPTION

Example:

INTERVAL 8:00-9:00 MEDICAL_LEAVE Doctor's appointment

Optionally, a date can be specified before the time range:

INTERVAL 2015-04-28 8:00-9:00 MEDICAL_LEAVE Doctor's appointment

Fetch (i.e., view) intervals

There are many commands for viewing intervals. In all cases, the term FETCH is optional

All intervals on the prompt date

INTERVAL [FETCH]

The simplest form; displays the list of intervals for the prompt date.

All intervals on a specified date

INTERVAL [FETCH] $DATE

Fetch all intervals on the given date. Example:

INTERVAL FETCH 2015-04-28

All intervals between a range of dates

INTERVAL [FETCH] $DATE_BEGIN $DATE_END
INTERVAL [FETCH] $DATE_BEGIN - $DATE_END

Fetch all intervals from $DATE_BEGIN to $DATE_END.

All intervals in a given month

INTERVAL [FETCH] $MONTH
INTERVAL [FETCH] $MONTH $YEAR

The month can be given either in English (only first three letters are necessary) or as a numeric value. Example:

INTERVAL APR
INTERVAL FETCH 4

Both of these commands fetch all the employee's intervals that fall within April of the prompt year.