By default, only the approval workflows are instrumented to generate audit records. This section describes how to use the com.waveset.session.WorkflowServices application to generate extra audit events from any workflow process.
Additional audit events may be required if you need to report on custom workflows. See Modifying Workflows to Log Standard Audit Events for information on adding audit events to workflows.
Special audit events can also be added to workflows in support of Workflow Reports (Workflow Reports). Workflow Reports report the amount of time it takes for workflows to complete. Special audit events are required to store the data necessary for time computations. See Modifying Workflows to Log Timing Audit Events for information on adding timing audit events to workflows.
The com.waveset.session.WorkflowServices application generates audit events from any workflow process. Table 10–1 describes the arguments that are available for this application.
Table 10–1 Arguments for com.waveset.session.WorkflowServices
Argument |
Type |
Description |
---|---|---|
op |
String |
Operation for WorkflowServices. Must be set to audit or auditWorkflow. Use audit for standard workflow auditing. Use auditWorkflow to store timing audit events required for time computations. Required. |
type |
String |
Name of the object type that is being audited. Auditable object types are listed in Table B–5. Required to log standard audit events. |
action |
String |
Name of the action performed. Auditable actions are listed in Table B–6. Required. |
status |
String |
Name of the status for the specified action. Status is listed in Table B–7 (in the Results column). Required to log standard audit events. |
name |
String |
Name of the object being affected by the specified action. Required to log standard audit events. |
resource |
String |
(Optional) Name of the resource where the object being changed resides. |
accountId |
String |
(Optional) Account ID that is being modified. This should be a native resource account name. |
error |
String |
(Optional) Localized error string to accompany any failures. |
reason |
String |
(Optional) Name of the ReasonDenied object, which maps to an internationalized message describing the causes of common failures. |
attributes |
Map |
(Optional) Map of attribute names and values that were added or modified. |
parameters |
Map |
(Optional) Maps up to five additional names or values that are relevant to an event. |
organizations |
List |
(Optional) List of organization names or IDs where this event will be placed. This is used for organizational scoping of the audit log. If not present, the handler will attempt to resolve the organization based on the type and name. If the organization cannot be resolved, the event is placed in Top (the highest level of the organizations hierarchy). |
originalAttributes |
Map |
(Optional) Map of old attribute values. The names should match the ones listed in the attributes argument. The values will be any previous value you want to save in your audit log. |
To create a standard audit event in a workflow, add the following <Activity> element to the workflow:
<Activity name=’createEvent’>
Next, nested in the <Activity> element, include an <Action> element that references the com.waveset.session.WorkflowServices application:
<Action class=’com.waveset.session.WorkflowServices’>
Nested in the <Action> element, include the required and optional <Argument> elements. See Table 10–1 for a list of the arguments.
To log standard audit events, the op argument must be set to audit.
Following are two examples that show the minimum code required to create a standard audit event.
The first example illustrates a simple workflow activity and shows the generation of an event that will log a resource deletion activity named ADSIResource1, performed by ResourceAdministrator.
<Activity name=’createEvent’> <Action class=’com.waveset.session.WorkflowServices’> <Argument name=’op’ value=’audit’/> <Argument name=’type’ value=’Resource’/> <Argument name=’action’ value=’Delete’/> <Argument name=’status’ value=’Success’/> <Argument name=’subject’ value=’ResourceAdministrator’/> <Argument name=’name’ value=’ADSIResource1’/> </Action> <Transition to=’end’/> </Activity> |
The second example illustrate how you can add specific attributes to a workflow that tracks the changes applied by each user in an approval process to a granular level. This addition typically will follow a ManualAction that solicits input from a user.
ACTUAL_APPROVER is set in the form and in the workflow (if approving from the approvals table) based on the person who actually performed the approval. APPROVER identifies the person to whom it was assigned.
<Action name=’Audit the Approval’ application=’com.waveset.session.WorkflowServices’> <Argument name=’op’ value=’audit’/> <Argument name=’type’ value=’User’/> <Argument name=’name’ value=’$(CUSTOM_DESCRIPTION)’/> <Argument name=’action’ value=’approve’/> <Argument name=’accountId’ value=’$(accountId)’/> <Argument name=’status’ value=’success’/> <Argument name=’resource’ value=’$(RESOURCE_IF_APPLICABLE)’/> <Argument name=’loginApplication’ value=’$(loginApplication)’/> <Argument name=’attributes’> <map> <s>fullname</s><ref>user.accounts[Lighthouse].fullname</ref> <s>jobTitle</s><ref>user.accounts[Lighthouse].jobTitle</ref> <s>location</s><ref>user.accounts[Lighthouse].location</ref> <s>team</s><ref>user.waveset.organization</ref> <s>agency</s> <ref>user.accounts[Lighthouse].agency</ref> </map> </Argument> <Argument name=’originalAttributes’> <map> <s>fullname</s> <s>User’s previous fullname</s> <s>jobTitle</s> <s>User’s previous job title</s> <s>location</s> <s>User’s previous location</s> <s>team</s> <s>User’s previous team</s> <s>agency</s> <s>User’s previous agency</s> </map> </Argument> <Argument name=’attributes’> <map> <s>firstname</s> <s>Joe</s> <s>lastname</s> <s>New</s> </map> </Argument> <Argument name=’subject’> <or> <ref>ACTUAL_APPROVER</ref> <ref>APPROVER</ref> </or> </Argument> <Argument name=’approver’ value=’$(APPROVER)’/> </Action> |
Workflows can be modified to log timing events in support of Workflow Reports (Workflow Reports). Standard audit events only log that an event occurred; Timing audit events log when an event started and stopped, making it possible to perform time computations. In addition to timing event data, most of the information logged by standard audit events is also stored. See What Information Do Timing Audit Events Store? for more information.
To log timing audit events, you must first activate workflow auditing for each workflow type that you plan to audit.
For workflows that you can configure in the Administrator interface using task templates, first enable the task template that corresponds to the workflow that you want to audit. See Enabling the Task Templates for instructions.
Next, turn on workflow auditing by selecting the Audit entire workflow checkbox. See Configuring the Audit Tab for instructions.
For workflows that do not have task templates, instead define a variable named auditWorkflow and set its value to true.
Note that auditing workflows degrades performance.
The Example 10–3 example shows the code required to create timing audit events. To log timing audit events, the op argument must be set to auditWorkflow.
The action argument is also required and must be set to one of the following values:
StartWorkflow
EndWorkflow
StartProcess
EndProcess
StartActivity
EndActivity
Additional action arguments may be defined in auditconfig.xml.
Example 10–3 illustrates enabling timing audit events in a workflow. To instrument a workflow, auditWorkflow events should be added at the beginning and end of workflows, processes, and activities.
The auditWorkflow operation is defined in com.waveset.session.WorkflowServices. See The com.waveset.session.WorkflowServices Application for more information.
<Action application=’com.waveset.session.WorkflowServices’> <Argument name=’op’ value=’auditWorkflow’/> <Argument name=’action’ value=’StartWorkflow’/> </Action> |
To stop logging timing audit events in a workflow, add the code in Example 10–4 to a pre-end activity near the conclusion of the workflow. Note that, when instrumenting a workflow or process, you are not permitted to put anything in an end activity. You must create a pre-end activity that performs the final auditWorkflow event, and then unconditionally transition to the end event.
<Action application=’com.waveset.session.WorkflowServices’> <Argument name=’op’ value=’auditWorkflow’/> <Argument name=’action’ value=’EndWorkflow’/> </Action> |
By default, timing audit events log most of the information stored by regular audit events, including the following attributes:
Attribute |
Description |
---|---|
WORKFLOW |
Name of the workflow being executed |
PROCESS |
Name of the current process being executed |
INSTANCEID |
Unique instance ID of the workflow being executed |
ACTIVITY |
Activity in which the event is being logged |
MATCH |
Unique identifier within a workflow instance |
The above attributes are stored in the logattr table and they come from auditableAttributesList. Waveset also checks whether the workflowAuditAttrConds attribute is defined.
It is possible to call some activities several times within a single instance of a process or a workflow. To match the audit events for a particular activity instance, Waveset stores a unique identifier within a workflow instance in the logattr table.
To store additional attributes in the logattr table for a workflow, you must define a workflowAuditAttrConds list, which is assumed to be a list of GenericObjects. If you define an attrName attribute within the workflowAuditAttrConds list, Waveset pulls attrName out of the object within the code, first using attrName as the key, and then storing the attrName value. All keys and values are stored as uppercase values.