App::Dochazka::CLI::Guide - Dochazka CLI Guide
Version 0.240
The CLI commands can be divided into four categories:
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.
GET
PUT
POST
DELETE
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:
The equivalent of DELETE interval/iid/24
DELETE interval/iid/24
The equivalent of POST docu/text with the request entity shown.
POST docu/text
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.
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.
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.
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.
ACTIVITY ALL DISABLED
Displays a list of all activities, including disabled activities.
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.
To accomplish this, we can use a REST test command:
PUT activity aid $AID { "disabled" : "t" } PUT activity code $CODE { "disabled" : "t" }
PUT activity aid $AID { "disabled" : "f" } PUT activity code $CODE { "disabled" : "f" }
Assuming nothing points to it, an activity can be deleted:
DELETE activity aid $AID DELETE activity code $CODE
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))
$NICK
$SEC_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.
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.
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).
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
To manually change an employee's full name, do one of the following:
EMPLOYEE_SPEC FULLNAME $WHATEVER EMPLOYEE_SPEC SET FULLNAME $WHATEVER
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.
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.
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
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".
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.
To see the current state of the working schedule, do:
SCHEDULE DUMP SCHEDULE MEMORY
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.
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
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 )
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
SCHEDULE SCODE 9_TO_5
The scode may not contain whitespace.
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.
The working schedule can be cleared:
SCHEDULE CLEAR
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.
$REMARK
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.
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" }
To re-enable a disabled schedule:
PUT SCHEDULE SID $SID { "disabled" : "f" } PUT SCHEDULE SCODE $SCODE { "disabled" : "f" }
Maintaining/updating employee history records (recording changes in privilege level and schedule, primarily) is a typical administrator workflow.
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.)
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
EMPLOYEE_SPEC SCHEDULE_SPEC _TIMESTAMP EMPLOYEE_SPEC SET SCHEDULE_SPEC _TIMESTAMP EMPLOYEE_SPEC SCHEDULE_SPEC EFFECTIVE _TIMESTAMP EMPLOYEE_SPEC SET SCHEDULE_SPEC EFFECTIVE _TIMESTAMP
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
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
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
Although EMPLOYEE_SPEC PROFILE shows the employee's privilege level, there is also a dedicated command:
EMPLOYEE_SPEC PROFILE
EMPLOYEE_SPEC PRIV
Provided the employee has a schedule defined, it can be displayed by typing:
EMPLOYEE_SPEC SCHEDULE
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.
EMPLOYEE_SPEC PRIV HISTORY
EMPLOYEE_SPEC SCHEDULE HISTORY
To view a list of all activities, do:
ACTIVITIES ACTIVITIES ALL
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
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.
Although EMPLOYEE PROFILE shows the employee's privilege level, there is also a dedicated command:
EMPLOYEE PROFILE
PRIV
Example
Dochazka(2015-04-08) demo PASSERBY> priv The current privilege level of demo (EID 2) is passerby
SCHEDULE
PRIV HISTORY
SCHEDULE HISTORY
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
Another way to omit the date (default to the prompt date) is to enter a time range:
INTERVAL $TIME_RANGE $ACTIVITY_CODE $DESCRIPTION
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
There are many commands for viewing intervals. In all cases, the term FETCH is optional
INTERVAL [FETCH]
The simplest form; displays the list of intervals for the prompt date.
INTERVAL [FETCH] $DATE
Fetch all intervals on the given date. Example:
INTERVAL FETCH 2015-04-28
INTERVAL [FETCH] $DATE_BEGIN $DATE_END INTERVAL [FETCH] $DATE_BEGIN - $DATE_END
Fetch all intervals from $DATE_BEGIN to $DATE_END.
$DATE_BEGIN
$DATE_END
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.
To install App::Dochazka::CLI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Dochazka::CLI
CPAN shell
perl -MCPAN -e shell install App::Dochazka::CLI
For more information on module installation, please visit the detailed CPAN module installation guide.