Workflow Execution Auditing and Reporting
Workflows may emit audit records by calling the audit()
function. The audit
function's only argument is a string that is to be placed into the audit log.
Using the audit()
function shows the actual user who executed the workflow only if setid
is set to false
. However, if a workflow is owned by root
and setid
is set to true
, audit logs will show root
as the user, even if the workflow was run by another user.
To determine the user that is executing the workflow regardless of what setid
is set to, use the whoami()
function.
Example 9-7 Workflow Testing whoami
Function
var workflow = { name: "Test whoami", description: "Print current username", execute: function () { return ("Hello " + whoami()); } };
For complicated workflows that may require some time to execute, it can be useful to provide clear progress to the user executing the workflow. To allow the execution of a workflow to be reported in this way, the execute
member should return an array of steps. Each array element must contain the following members:
Table 9-6 Required Members for Execution Reporting
Required Member | Type | Description |
---|---|---|
|
String |
String that denotes the name of the execution step |
|
Function |
Function that executes the step of the workflow |
As with the execute
function on the workflow as a whole, the execute
member of each step takes as its argument an object that contains the parameters to the workflow.
Example 9-8 Workflow Execution Reporting
As an example, the following is a workflow that creates a new project, share, and audit record over three steps:
var steps = [ { step: 'Checking for associated project', execute: function (params) { try { run('shares select ' + params.unit); } catch (err) { if (err.code != EAKSH_ENTITY_BADSELECT) throw (err); /* * We haven't yet created a project that corresponds to * this business unit; create it now. */ run('shares project ' + params.unit); set('mountpoint', '/export/' + params.unit); run('commit'); run('shares select ' + params.unit); } } }, { step: 'Creating share', execute: function (params) { run('filesystem ' + params.name); run('commit'); } }, { step: 'Creating audit record', execute: function (params) { audit('created "' + params.name + '" in "' + params.unit); } } ]; var workflow = { name: 'Create share', description: 'Creates a new share in a business unit', parameters: { name: { label: 'Name of new share', type: 'String' }, unit: { label: 'Business unit', type: 'ChooseOne', options: [ 'development', 'finance', 'qa', 'sales' ], optionlabels: [ 'Development', 'Finance', 'Quality Assurance', 'Sales/Administrative' ], } }, validate: function (params) { try { run('shares select ' + params.unit); run('select ' + params.name); } catch (err) { if (err.code == EAKSH_ENTITY_BADSELECT) return; } return ({ name: 'share already exists' }); }, execute: function (params) { return (steps); } };
Using the mail
function, workflows can deliver certain outputs of the workflow via email. The mail
function must contain the following arguments: an object with to
and subject
, and a messageBody
string.
Example 9-9 Workflow Execution with a Mailer
var workflow = { name: 'email controller state', description: 'email controller state', execute: function () { // verify state of the controller var faulted = run('maintenance hardware "chassis-000" get faulted'); var messageBody = faulted; emailAddress = 'first.last@xyz.com'; subjectLine = 'Controller State'; mail({To: emailAddress, Subject: subjectLine}, messageBody); } };