Purging Audit Data

The audit entries for a process instance are not required once the process instance completes, is cancelled, or has failed.

The EventCollectorManagementService API (which is one of the Event Collection Services provided by Process Manager) provides operations to manage purges of audit data from the Event Collector database tables—that is, to delete the audit entries and statistical data for completed, cancelled, and failed process instances.

The EventCollectorManagementService provides the following web service operations (SOAP) / Service Connector methods (Java):

• doPurgeAudit - This operation purges data from the Event Collector database tables. Its options enable you to define the scope of the purge.
• stopPurgeAudit - This operation stops an ongoing purge.
• checkPurgeAudit - This operation checks the status of an ongoing purge.
  Note: Note that:

  • The functionality provided by this service is equivalent to that of the administrator-initiated stored procedures described in the section "Clearing Audit Entries and Statistical Data" in the TIBCO ActiveMatrix BPM - BPM Administration guide.

    The performance of the data purges described in this section will be greatly improved if you create the same database indexes that you are recommended to use with these stored procedures. See the section "Clearing Audit Entries and Statistical Data" in the TIBCO ActiveMatrix BPM - BPM Administration guide for the syntax to use for each of the supported database types.

  • Neither the EventCollectorManagementService API nor these stored procedures include any provision for backing up or archiving your database. TIBCO recommends that you backup your database, according to whatever backup strategy your organization has implemented, before running doPurgeAudit or initiating the equivalent stored procedure. Refer to the documentation supplied with your database server for information on how to do this.

An example of the doPurgeAudit operation is as follows:

<soapenv:Body>
   <api:doPurgeAuditRequest>
      <options>
        <batchSize>200</batchSize>
        <threshold>2013-02-10T11:34:22.222Z</threshold>
        <processTemplates>
           <processTemplateIdIdentifier>
              <processTemplateId>004</processTemplateId>
           </processTemplateIdIdentifier>
           <processTemplateNameIdentifier>
              <processTemplateName>TestClaim</processTemplateName>
              <moduleName>/ClaimsProc/Process Packages/ProcessPackage.
                 xpdl</moduleName>
              <version>1.1.0.201105061158</version>
           </processTemplateNameIdentifier>
           <processTemplateNameIdentifier>
              <processTemplateName>Refund</processTemplateName>
              <moduleName>/ClaimsProc/Process Packages/ProcessPackage.xpdl
              </moduleName>
              <version>1.1.0.201105061032</version>
           </processTemplateNameIdentifier>
        </processTemplates>
      </options>
   </api:doPurgeAuditRequest>
</soapenv:Body>

<SOAP-ENV:Body>
    <statusMessage>Purge Operation [EC-PURGE-1351517760674] started at Fri Mar 29 13:36:00 GMT 2013 finished at Fri Mar 29 13:36:01 GMT 2012 with success! 11 instances of total 11 deleted!</statusMessage>
    <status>PURGE_COMPLETED</status>
</SOAP-ENV:Body>

The default values for the parameters to this operation are:

The runInBackground option enables you to choose whether to run the doPurgeAudit operation in the background, or not. By default it is true, so doPurgeAudit immediately returns the value In Progress, and is then available for other operations. Note, however, that doPurgeAudit does not then give any response to indicate when the background purge finally is completed; but you can monitor the status of the purge using the checkPurgeAudit operation.

If you set runInBackground to false, the EventCollectorManagementService waits for the purge to finish (subject to any timeouts that may prevent it waiting) before returning the status of the purge (PURGE_COMPLETED, in the case of a successful purge) or starting any other operation.

The threshold option is a date value, and specifies that only process instances that have completed, cancelled, or failed before that date are eligible to be purged. You can use this value to ensure that data is only deleted after a certain time has elapsed, to enable any necessary reporting to be completed.

You can specify the templates to be considered for purging by using either or both of:

• Using processTemplateNameIdentifier to specify the template name. You can simply give a processTemplateName, if this name is unique on the system and can therefore uniquely identify a template. If the name may not be unique, you can also specify the moduleName and the version number of the template, to uniquely identify the template required.
• Using processTemplateIDIdentifier to specify the template ID.

You can mix these two forms of identifier in the same call to the doPurgeAudit operation.