BPMProcessInstancesPurge command

Use this command to delete business process definition (BPD) instance data and associated documents for a process application snapshot on Workflow Server.

Using this command deletes the BPD instance and its associated tasks and documents for the instances that are specified by the command parameters. It also logs data to a standard systemout.log file to track which filter criteria was selected for deleting instance data and associated documents.
This topic applies only to the IBM Business Automation Workflow Advanced configuration.Remember: You cannot use this command to delete BPEL processes. Use the deleteCompletedProcessInstances.py and deleteCompletedTaskInstances.py administrative scripts to delete BPEL processes. For information about these scripts, see deleteCompletedProcessInstances.py administrative script and deleteCompletedTaskInstances.py administrative script
The BPMProcessInstancesPurge command is run by using the AdminTask object of the wsadmin scripting client.
Important: Wait for the command to complete before you run it again.

Prerequisites

Note: In an environment with multiple security domains configured, use the PALService MBean instead of this wsadmin command. See The Process Application LifeCycle (PAL) MBean.
The following conditions must be met:
  • Run the command in the connected mode, that is, do not use the wsadmin -conntype none option.
  • This topic applies only to the IBM Business Automation Workflow Advanced configuration.To run this command, you must be a user in the DeAdmin role. In a network deployment environment, you must run this command on the node that contains the application cluster member that handles Workflow Server applications. Do not run this command from the deployment manager profile.
  • This topic applies only to the IBM Business Automation Workflow Advanced configuration.You cannot use this command to delete BPEL processes.
  • You can run the command from any cluster member in a network deployment environment. However, you must first establish the wsadmin session to the SOAP port of the cluster member from where you are running the command.

Location

Start the wsadmin scripting client from the install_root/bin directory.

Syntax

BPMProcessInstancesPurge
-instanceStatus instance_statuses
[-containerAcronym process_application_acronym]
[-containerSnapshotAcronym process_application_snapshot_acronym]
[-endedAfterLocal local_time_on_the_server]
[-endedBeforeLocal local_time_on_the_server]
[-instanceID instance_ID]
[-maximumDuration number_of_minutes]
[-outputFile file_path]
[-transactionSlice number_of_instances_to_delete_in_a_transaction]
[-force]

Parameters

-instanceStatus instance_statuses
A required parameter of type String[] that identifies the statuses of process instances to purge.
  • COMPLETED - Removes all completed process instances.
  • TERMINATED - Removes all terminated process instances.
  • FAILED - Removes all failed process instances.
  • DID_NOT_START - Removes all process instances that are in the did not start state.
  • SUSPENDED - Removes all suspended process instances.
  • ACTIVE - Removes all active process instances.
  • ALL - Removes all process instances.
Important: If you want to delete instances that are not in an end-state (COMPLETED or TERMINATED), you must specify the -force option.
-containerAcronym process_application_acronym
An optional parameter of type String that identifies the acronym that specifies the process application for which process instances are purged. For example, the BillingDispute process application might have an acronym BILLDISP. This parameter is required if the containerSnapshotAcronym parameter is specified
-containerSnapshotAcronym process_application_snapshot_acronyms
An optional parameter of type String[] that identifies the snapshot acronyms for the specified process application. The snapshot acronyms can be different from the snapshot name.
Important: Be careful when you delete instances from a snapshot that was recently created because it might affect TIP instances.
Tip: To find a snapshot acronym, run the BPMShowProcessApplication command. For more information, see BPMShowProcessApplication command.
-endedAfterLocal local_time_on_the_server
An optional parameter of type String that identifies the local time on the server. The string must have the following format: yyyy-MM-ddThh:mm:ss (year, month, day, T, hours, minutes, seconds). Only instances that completed or terminated after the time that is specified by this parameter are processed. If you use this parameter with the endedBeforeLocal parameter, only instances that completed or terminated during the specified time period by this parameter are processed. This parameter's value refers to the date when the instance reached its end state.
Note: If you specify this parameter and the instanceStatus parameter is set to ALL, there may be unexpected results because only process instances that are in the COMPLETED or TERMINATED state can have an end date. Process instances that are in a different state cannot be purged because they do not fulfill the time condition.
-endedBeforeLocal local_time_on_the_server
An optional parameter of type String that identifies the local time on the server. The string must have the following format: yyyy-MM-ddThh:mm:ss (year, month, day, T, hours, minutes, seconds). Only instances that completed or terminated before the time that is specified by this parameter are processed. If you use this parameter with the endedAfterLocal parameter, only instances that completed or terminated during the specified time period by this parameter are processed. This parameter's value refers to the date when the instance reached its end state.
Note: If you specify this parameter and the instanceStatus parameter is set to ALL, there may be unexpected results because only process instances that are in the COMPLETED or TERMINATED state can have an end date. Process instances that are in a different state cannot be purged because they do not fulfill the time condition.
-instanceID instance_ID
An optional parameter of type String[] that identifies a list of IDs of instances to remove. If there is more than one instance ID, each instance ID must be delimited by a space for Jython format commands or a semicolon for JACL format commands. You can also use this parameter with endedAfterLocal or endedBeforeLocal.
-maximumDuration number_of_minutes
An optional parameter of type Integer that specifies the maximum deletion time in minutes. If the cleanup takes longer than the time specified by this parameter, the current transaction slice for the current cleanup job is completed, and then the current cleanup job is stopped. The default value is 0, which indicates that there is no limit.
-outputFile file_path
An optional parameter that provides a qualified file path to write the process instance cleanup log entries. The default is systemout.log.
-transactionSlice number_of_instances_to_delete_in_a_transaction
An optional parameter that specifies the number of instances that are deleted per transaction. The default value is 10. Check the SystemOut.log file for any exceptions if the cleanup service adjusted your transactionSlice. Adjusting the value that is used can improve the speed of the cleanup operation.
-force
An optional parameter that becomes required if you want to delete instances that are not in an end state. End states are COMPLETED and TERMINATED.

Using the BPMProcessInstancesPurge command

In a network deployment environment, use the port that is configured for the application cluster member that runs the Workflow Server or Workflow Center applications.
Tip: To determine the correct port number, view the WebSphere administrative console Ports collection page by clicking Servers > Server Types > WebSphere application servers > server_name > Communications > Ports, and locate the value for SOAP_CONNECTOR_ADDRESS.

The following sections provide some illustrative examples of using the command.

Example: Deleting instances and associated tasks

wsadmin -conntype SOAP -port 8880 -host ProcessServer01.example.com -user admin -password admin -lang jython 

wsadmin>AdminTask.BPMProcessInstancesPurge('[-containerAcronym PA435 -containerSnapshotAcronym V1 -instanceStatus FAILED -outputFile C:\US58626\log1.txt]')

wsadmin>AdminTask.BPMProcessInstancesPurge('[-containerAcronym PA435 -containerSnapshotAcronym [V1 V2] -instanceStatus FAILED -force -outputFile C:\US58626\log1.txt]')

Example: Deleting instances, based on the instance ID

wsadmin -conntype SOAP -port 8880 -host ProcessServer01.example.com -user admin -password admin -lang jython 

wsadmin>AdminTask.BPMProcessInstancesPurge('[-containerAcronym BILLDISP -containerSnapshotAcronym SS2.0.1 -instanceStatus TERMINATED -force -instanceID [4 5 1001 1002]]')

Example: Deleting instances that completed or terminated during a specific time period

wsadmin -conntype SOAP -port 8880 -host ProcessServer01.example.com -user admin -password admin -lang jython 

wsadmin>AdminTask.BPMProcessInstancesPurge('[-containerAcronym BILLDISP -containerSnapshotAcronym SS2.0.1 
          -instanceStatus ALL -endedAfterLocal 2015-01-01T00:00:00 -endedBeforeLocal 2015-02-31T21:37:06 -force]')
In this case, although -instanceStatus ALL selects instances in all states, because a time period is also specified, the selection for deletion is reduced to instances that completed or terminated in the time range.

Sample entries in SystemOut.log to confirm that the command ran

wsadmin>AdminTask.BPMProcessInstancesPurge('[-containerAcronym HSS -instanceStatus TERMINATED 
      -endedBeforeLocal 2016-11-02T21:37:06]')'The BPMProcessInstancesPurge command passed.'
SystemOut.log entry:

[11/1/16 14:22:45:532 PDT] 000001cc CommandServic I PALAdminCommands otherProcessInstancesPurge Entering
[11/1/16 14:22:45:553 PDT] 000001cc Log           I   PAL: About to delete the process instances matching the filter criteria: 
SnapshotIDs: [Snapshot.f1659d94-2365-4903-8a90-9fa62f3ccc97, Snapshot.95fb38c2-50b4-4ba7-b3e9-24e72254233b]
Statuses: [4]
Ended before: 2016-11-02 21:37:06.0
Maximum duration: 0
Transaction slice: 10

[11/1/16 14:22:45:554 PDT] 000001cc Log           I   PAL: Number of qualifying instances before deletion: 1
[11/1/16 14:22:45:664 PDT] 000001cc Log           I   PAL: A deletion job is running. Progress: Deleted 1 instance(s).
[11/1/16 14:22:45:665 PDT] 000001cc Log           I   PAL: Every instance has been deleted. The deletion job finished.
[11/1/16 14:22:45:676 PDT] 000001cc Log           I   PAL: Successfully deleted the process instances matching the filter criteria: 
SnapshotIDs: [Snapshot.f1659d94-2365-4903-8a90-9fa62f3ccc97, Snapshot.95fb38c2-50b4-4ba7-b3e9-24e72254233b]
Statuses: [4]
Ended before: 2016-11-02 21:37:06.0
Maximum duration: 0
Transaction slice: 10

[11/1/16 14:22:45:677 PDT] 000001cc Log           I   PAL: Number of qualifying instances before deletion: 1
[11/1/16 14:22:45:689 PDT] 000001cc Log           I   PAL: Number of qualifying instances after deletion: 0
[11/1/16 14:22:45:693 PDT] 000001cc CommandServic I PALAdminCommands otherProcessInstancesPurge Exiting