AuditService

The AuditService contains functions to manage purges of audit entries, submit events for audit by Event Collector, and get audit information from the Event Collector database tables.

The table below lists the functions available from the AuditService.

For more information about audit events, see Events.

Function Description Returns
addCaseComment

--or--

addCaseCommentAlt

Stores a comment against a case. You can use these comments to create a custom audit trail.

For more information, see Comments.

Required system action: queryAudit

Comment
addProcessInstanceComment Stores a comment against a process instance. You can use these comments to create a custom audit trail.

For more information, see Comments.

Required system action: queryAudit

Comment
addWorkItemComment

--or--

addWorkItemCommentAlt

Stores a comment against a work item. You can use these comments to create a custom audit trail.

For more information, see Comments.

Required system action: queryAudit

Comment
checkAutoArchive Checks whether an archive is currently running. It returns the status of the last archive that ran. If the archive is currently running, it also returns the status of the archive that is currently running.

Required system action: none

CheckAutoArchiveResponseObject
checkPurge Checks the status of a purge started with the doPurge function (see below).

Required system action: none

PurgeStatus
doPurge Purges data related to completed, cancelled, and failed process instances from the Event Collector database tables.

You can specify the process templates to be purged either by ID or by name and version, as well as other options that limit the extent of the purge.

Note: TIBCO recommends that you back up your database before running doPurge. For more information, see Purging Audit Data.

Required system action: none

PurgeStatus
event Submits an event to the Event Collector database.
Note:
  • You submit a particular instance of an event to Event Collector if you want that event to be audited. See the "Audit" chapter in TIBCO ActiveMatrix BPM Administration for details of how to set up auditing.
  • You can submit details of any of the event's attributes, provided that they have previously been registered using the registerAttributes function (see below).
  • There is no response to this operation. If it is necessary to confirm whether the eventRequest has been correctly received, you can query the database. See "Working with Events and the TIBCO ActiveMatrix BPM Event Collector Schema Reference for information about querying the database.

Required system action: none

Empty response (no JSON payload)
executeGenericQuery Executes the specified query against the Event Collector database tables.

If a query needs to be executed multiple times, better performance will be experienced by registering the query with registerQuery, then using the executeRegisteredQuery function.

Required system action: none

ExecuteQueryResponseType
executeRegisteredQuery Executes a query that has been previously registered using the registerQuery function.
Note:
  • When queries are registered they are represented both by a GUID returned by the registration, and also by a tag which is passed in when registering.
  • The request must specify the previously registered query that is to be executed, along with any options to be used on this particular execution of the query.
  • The response returns details of the events that match the specified query, along with summary information about the executed query.

Required system action: none

GenericResult
getAttributes Lists all attributes in the Event Collector database tables that are registered for a specific component.

Required system action: none

AttributeDefinitions
getCaseComments Retrieves comments that have been stored against a case object, by specifying a managedObjectId.

Also see getSearchCaseComments, in which you can pass a case reference instead of a managedObjectId.

For more information, see Comments.

Required system action: queryAudit

CommentAudit
getCaseReport Generates an audit trail for the given case class.

Required system action: none

CaseAudit
getChart Aggregates the data in an Event Collector area (work items, cases, process templates, process instances, or events) to obtain audit information about the area.

This operation aggregates, and returns, the audit information in a tabular format, which is consumable by charting libraries such as Highcharts.

Also see the BPMChartService component service.

Required system action: queryAudit

ChartResult
getChartData Returns audit information for a specified Event Collector area (work items, cases, process templates, process instances, or events) based on specified filter criteria. For example, you can request all outstanding work items whose status is OFFERED.

This operation returns the audit information in a tabular format, which is consumable by charting libraries such as Highcharts.

Also see the BPMChartService component service.

Required system action: queryAudit

ChartDataResult
getComponents Lists the components that are registered on the system.

Required system action: none

getComponentsResponseObject
getProcessInstanceReport Generates an audit trail for a given process instance.

The request contains the ID of the process instance. Optionally, you can specify how the information is displayed.

Required system action: none

ProcessInstanceAudit
getProcInstComments Retrieves comments stored against a specified process instance.

For more information, see Comments.

Required system action: queryAudit

CommentAudit
getSearchCaseComments Retrieves comments that have been stored against a case, by specifying a case reference.

Also see getCaseComments, in which you can pass a managedObjectId instead of a case reference.

For more information, see Comments.

Required system action: queryAudit

CommentAudit
getSearchCaseReport Generates an audit trail for the given case data.

Required system action: none

CaseAudit
getWorkItemComments Retrieves comments stored against a specified work item.

For more information, see Comments.

Required system action: queryAudit

CommentAudit
getWorkItemReport Generates an audit trail for a given work item.

The request contains the ID of the work item. Optionally, you can specify how the information is displayed.

Required system action: none

WorkItemAudit
isQueryRegistered Tests whether a query is registered with Event Collector. (This can be useful for determining whether a frequently used query tag is already present on the system.)

Required system action: none

QueryRegisteredResponseObject
lookupQueryByTag Lists the details for a particular query (identified by its tag). This function can be used to obtain the GUID for a registered query.
Note: The executeRegisteredQuery function (see above) executes faster if the query is identified using its GUID rather than its tag.

Required system action: none

lookupQueryByTagResponseObject
registerAttributes Registers attributes with the Event Collector database.

Before you can audit an event, you must have registered with Event Collector any attributes used. You can register more than one attribute with the registerAttributes function. When registering an attribute, you must specify the component it is being registered against.

Warning: Do not register any attributes against existing TIBCO components. Doing so will cause TIBCO ActiveMatrix BPM to fail the next time you attempt to start it. You should only register attributes against custom components.

The attributes delivered as part of TIBCO ActiveMatrix BPM are already registered.

Required system action: none

RegisterAttributesResponseObject
registerComponent Registers a component with the Event Collector database.

You need to register a component if you have added a custom component to TIBCO ActiveMatrix BPM, and you intend to audit messages produced by that component. The TIBCO components that make up TIBCO ActiveMatrix BPM (such as BRM or Event Collector) are already registered.

Use the getComponents function (see above) to see what components are registered.

Attributes are registered against a registered component, so you must register a component first before you can use the registerAttributes function (see above) to register attributes against that component, or use the event function (see above) to audit messages that relate to that component.

Required system action: none

registerComponentResponseObject
registerQuery Registers a query with Event Collector, so that it can be subsequently executed using the executeRegisteredQuery function (see above).

Required system action: none

registerQueryResponseObject
stopAutoArchive Stops an archive operation that is currently running. The archive operation may not be able to stop immediately, but will stop as soon as possible.

Required system action: none

StopAutoArchiveResponseObject
stopPurge Stops a purge started with the doPurge function (see above).

The request can either call for a simple status message, or can specify options that specify the data to be returned as fields in the purgeStatus object.

Required system action: none

PurgeStatus
triggerAutoArchive Starts an archive, if it is not currently running. If the archive overlaps the time that the next archive is scheduled to run, the archive will not run and the next archive will take place at the next scheduled time.

If you have disabled automatic archiving by specifying autoArchiveEnabled=false in the ec.properties file, then try and trigger an archive using triggerAutoArchive, the archive operation will not be triggered. No warning or error is returned to inform you that the archive operation has not been triggered.

Required system action: none

AutoArchiveOptions
unregisterQuery Unregisters a previously registered query.

Required system action: none

UnRegisterQueryResponseObject