Audit of Custom Work Item Attributes

Configurable Auditing

Once you have specified that the user-defined attributes should be audited, you can then configure more specifically which of the attributes are to be audited for which particular messages, by adding further rules to the file. You can configure auditing so that:

• Either all of the 40 user-defined attributes or a subset of them are audited,
• The defined attributes are audited either for all of the supported messages, or for only a subset of the supported messages,
• The defined attributes for the defined messages can be filtered further by the user task name. This is achieved by an expression condition in the rules file that results in a query, and running such queries may have a significant impact on performance. See Expressions for more information on expression conditions.

For example, the following are some of the ways that you can configure the way that attributes are propagated for auditing:

• Propagate all attributes for all supported user task messages.
• Propagate a subset of attributes for all supported user task messages.
• Propagate all attributes for a subset of supported user task messages.
• Propagate a subset of attributes for a subset of supported user task messages.
• Propagate all attributes for all supported user task messages for one or more specific user tasks.
• Propagate a subset of attributes for all supported user task messages for one or more specific user tasks.
• Propagate all attributes for a subset of supported user task messages for one or more specific user tasks.
• Propagate a subset of attributes for a subset of supported user task messages for one or more specific user tasks.
  Note:

  • Note that any arrangement that restricts attribute auditing to specific user tasks will have an impact on performance.
  • Any attributes used in an expression must be included in the event being audited. For example, if the expression is making a decision based on the user task name and template name then the attributes containing these values must be present in the event. See List of Messages for information on which attributes are found in which messages.

You can set up one or more of the above rules at the same time. The rules are executed in numerical order, based on the ruleOrder attribute of the rule. When there is more than one rule defined in the file, the rules Engine works through the list of rules until it matches a rule. At that point it exits. Therefore, the numerical order of the rules is important, both in terms of which rule is actually executed and because any rule that is resource-intensive to check should be last in the list of rules.

Example

Assume that the following rules are defined:

• Propagate attribute2 and attribute3 for message BRM_WORKITEM_OPENED.
• Propagate attribute7 for message BRM_WORKITEM_OPENED for user task Confirm Invoice.
• Propagate attribute7 for message BRM_WORKITEM_CLOSE for user task Confirm Invoice.

With these three rules defined and with ruleOrder attributes that mean they are executed in this order, then:

• Attribute2, attribute3 and attribute7 will be propagated for message BRM_WORKITEM_OPENED for user task Confirm Invoice.
• Attribute7 will be propagated for message BRM_WORKITEM_CLOSE for user task Confirm Invoice.
• Attribute2 and attribute3 will be propagated for message BRM_WORKITEM_OPENED for user task Create Invoice.

The following extract shows how the rule listed as point 1 above would be specified within the file. First, a new messageProcessDefinition called CentralECAuditProcessAttr2And3 is set up, as shown in the following illustration. This process specifies that custom attributes attribute2 and attribute3 are included in auditing.

<messageProcessDefinition name="CentralECAuditProcessAttr2And3" parentMessageProcess="CentralECAuditProcessExclusions">
  <includedAttributesList>
    <attribute>attribute2</attribute>
    <attribute>attribute3</attribute>
  </includedAttributesList>
  
</messageProcessDefinition>

Then the file defines a new rule. This is numbered 600 so that it is executed before the existing rule 800. This rule prescribes that the specific message ID BRM_WORKITEM_OPENED should be processed using the new messageProcessDefinition CentralECAuditProcessAttr2And3.

<rules>
  <rule name="AuditMessageWithAttr2And3" ruleOrder="600">
    <filter>
      <messageIds>
        <messageId>BRM_WORKITEM_OPENED</messageId>
      </messageIds>
    </filter>
    <action>
      <messageProcess>CentralECAuditProcessAttr2And3</messageProcess>
    </action>
  </rule>

The two custom attributes are therefore included in auditing, for the named message only, before rule 800 can exclude them.

Expressions

Expressions can be used as part of filters in the ec-probe-rules.xml or ec-event-rules.xml files, and are introduced by the <expression tag. Expressions use the same syntax that is defined for queries in "Working with Events" in the TIBCO ActiveMatrix BPM Developer’s Guide.

When processing rules, EventCollector will always process the expression rule last, to attempt to avoid needing to use it.

For example:

<filter>
     <expression>(attribute8='abc')</expression>
</filter>

This expression restricts the application of the rule to messages that have a value for the user-defined attribute attribute8 of 'abc'.

To implement the second rule listed above, to propagate attribute7 (as well as the default attributes) for message BRM_WORKITEM_CLOSE for user task Confirm Invoice, you could:

• Define a MessageProcessDefinition as in the first example) which includes the default attributes and adds attribute7. For example:

  <messageProcessDefinition name="ImplementRule2">
    <includedAttributesList>
      <allPrimaries>true</allPrimaries>
      <attribute>attribute7</attribute>
    </includedAttributesList>
  </messageProcessDefinition>

• Define a rule which:
  • Using an expression, limits its application to message BRM_WORKITEM_CLOSE with user task Confirm Invoice,
  • Uses the message process definition that you defined in the previous step,
  • Has a ruleOrder number low enough that it will be implemented before any other rule that might catch this message.
    For example:

    <rule name='Rule2Rule" ruleOrder='200'>
    	<filter>
    		<expression>applicationActivityInstanceId = 'Confirm Invoice'</expression>
    		<messageIds>
    			<messageId>BRM_WORKITEM_CLOSE</messageId>
    		</messageIds>
    	</filter>
    	<action>
    		<messageProcess>ImplementRule2</messageProcess>
    	</action>
    </rule>
    

<filter>
	<expression>attribute8='abc'</expression>
	<messageIds>
		<messageId>BRM_WORKITEM_OPENED</messageId>
	</messageIds>
</filter>

Further Editing