With the 0.1.49 release [and currently available in the 0.1.49rc releases]
OpenGroupware Coils exposes the workflow scheduler via WebDAV at the path "
/dav/Workflow/Schedule". This collection [folder] allows enumeration of schedule entries by WebDAV clients or via REST, as well as the creation and deletion of schedule entries.
Each entry is represented by a JSON serialized resource. These resources can be retrieved via GET, created via PUT, or removed via DELETE. For REST clients the resource "
/var/Workflow/Schedule/.contents" will return a JSON encoded list of all the folder entries. Via either RPC mechanism clients only see the schedule entries available to their own security context.
$ cat send-request.json
{"routeId":1158480,"priority":300,"repeat":1,"type":"interval","minutes":2}
$ curl -vvvv -u adam:******* -X PUT --upload-file send-request.json http://127.0.0.1:8080/dav/Workflow/Schedule/request
...
< Location: /dav/Workflow/Schedule/0f6bd804a4f14cf6a2807dad625e2bb1.json
< X-OpenGroupware-ScheduleEntryUUID: 0f6bd804a4f14cf6a2807dad625e2bb1
...
Create a scheduler entry where an instance of the route with the objectId 1158480 will be created two minutes from the current time having a priority of 300. The schedule will only occur once.
The required keys in the JSON data are: "
routeId" and "
type". The keys "
priority", "
contextId", "
xattrDict", "
attachmentUUID", and "
repeat" are optional. If unspecified the priority for scheduled entries will be 200, they will repeat without limit according to their schedule, and have the context of the currently authenticated user. A user may only create schedule entries with contexts that are available to them. Additional keys are required or optional based upon the value of "
type" which describes the kind of scheduling entry to create: "
simple", "
interval", or "
cron".
If the workflow requires an input message an attachment may be created via the
AttachFS protocol and the UUID of that attachment then specified in the scheduling entry; at run time the content of the attachment will be read into the input message of the new process. The attachment's UUID is sent in the "
attachmentUUID" attribute of the scheduling request.
In the future it will also be possible to specify a project document as an input message. Project documents have the advantages over attachments that they have a security descriptor and can be modified in-place.
Using the "
xattrDict" attribute a dictionary of key and values can be declared that will be applied to a new process as its XATTR values.
An "
interval" schedule type must specify at least one of the following values: "
weeks", "
days", "
hours", "
minutes", "
seconds". The type of any of these values must be an integer. Multiple values may be specified and their accumulative value will specify the frequency the process will be run.
A "
simple" schedule requires on a "
date" value; this specifies a specific time when the process will be created. "
simple" schedule entries do not repeat.
The "
cron" type schedule entry requires at least one of the following values: "
year", "
month", "
day", "
weekday", "
hour", or "
minute". All these are crontab style pattern matching strings; both division and comma separated lists are supported. Any of these values if not specified default to the string "
*".
All date/time values must be in UTC and expressed in either "
%Y%m%dT%H%M%S" or "
%Y-%m-%d %H:%M:%S" format. In either format the seconds value is optional, and if provided is ignored. Remember that the OIE scheduler is a best-effort scheduler - it will attempt to create the process within a minute of the time indicated by the schedule, but delay is possible. Also the scheduler only creates the process and queues it for execution. It is up to the workflow manager component when the process will actually be executed/performed. A variety of factors can influence the timing of process's execution, including singletons, system load, and administrative holds.
A schedule entry retrieved from the server will have all possible fields filled in as well as having two additional read-only fields: "
iterationsPerformed" and "
iterationsRemaining". "
iterationsPerformed" records how many times the schedule entry has been executed and "
iterationsRemaining" indicates how many addition additional iterations remain. A value of
-1 in "
iterationsRemaining" means the schedule entry will continue indefinitely; this field will only have a real value if "
repeat" was specified when the scheduler entry was created. If the entry has a repeat limit the "
iterationsRemaining" serves as a count down to the expiration of the entry, once the remaining iteration count reaches zero the schedule entry will be automatically deleted.
{"dayOfWeek": "3,5", "week": "*", "nextIteration": "2012-11-11T23:00:00", "month": "*", "second": "0", "iterationsRemaining": -1, "year": "*", "day": "*", "minute": "0", "attachmentUUID": null, "xattrDict": {"start": "$__MONTHSTART__;", "end": "$__TODAY__;"}, "contextId": 15211340, "UUID": "{c658993a-dcf1-410b-8003-5dc134feb564}", "hour": "23", "routeId": 70470079, "priority": 200, "iterationsPerformed": 7, "type": "cron"}
A complete schedule entry as retrieved from the server. Each time this entry creates a process that process will have a "start" XATTR whose value represents the date for first of the current month and an "end" XATTR that represents the current date.
For additional flexibility the OIE built-in labels are supported in the value of process XATTRs (specified in the schedule entry's "
xattrDict" value). The values will be substituted each time a new process is created from the schedule entry. Using built-in labels is especially useful when creating schedules for workflow processes that require a date range.
Process XATTR's and label substitution is documented in the Coils edition of WMOGAG.
