Creating Audit Events From Workflows

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

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.

Modifying Workflows to Log Standard Audit Events

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.

Example 10–1 Simple Workflow Activity

<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.

Example 10–2 Attributes Added to Track Changes in an Approval Process

 
<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>

Modifying Workflows to Log Timing Audit Events

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.

Examples: Starting and Stopping Audit Events in a Workflow

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.

Example 10–3 Starting Timing Audit Events in a Workflow

<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.

Example 10–4 Stopping Timing Audit Events in a Workflow

<Action application=’com.waveset.session.WorkflowServices’> 
<Argument name=’op’ value=’auditWorkflow’/> <Argument name=’action’ value=’EndWorkflow’/> 
</Action>

What Information Do Timing Audit Events Store?

By default, timing audit events log most of the information stored by regular audit events, including the following attributes:

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.