Copyright © Cloud Software Group, Inc. All Rights Reserved

Engine Command

Activity

The Engine Command activity allows you to retrieve statistics and information about process definitions, process instances, and activities in the currently running process engine. This activity also lets you perform engine maintenance, such as suspending and resuming process instances and shutting down the engine.

This activity uses TIBCO Hawk to perform the desired command. A direct call is made to the TIBCO Hawk AMI method (no message is sent).

Before using this activity, the Hawk.Enabled property must be set to either true or local. Also, some commands require memory and processor overhead for gathering statistics or for getting information on the current state of the process. Because of the performance implications, certain instrumentation is disabled by default. You can enable instrumentation for a specific process or for all processes with the Instrumentation property. See TIBCO ActiveMatrix BusinessWorks Administration for more information about setting custom engine properties.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
Command to Execute	No	The command to execute. See Commands for more information about the commands and their input and output.
Process Definition Name	No	Certain commands accept a process definition name. This field allows you to specify the process definition name that applies to the selected command. This field only appears when the one of the following commands is selected in the Command to Execute field: • GetActivityStats • GetProcessInstanceInfo • ResumeProcessStarter • SuspendProcessStarter

Input

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

Input Item	Datatype	Description
<commandInput>	varies	The input for this activity varies depending upon the command selected in the Command to Execute field on the Configuration tab. See Commands for more information about the input for each command.

Output

The output for the activity is the following.

Output Item	Datatype	Description
<commandOutput>	varies	The output for this activity varies depending upon the command selected in the Command to Execute field on the Configuration tab. See Commands for more information about the output for each command.

Commands

The following are the commands that can be executed by this activity and the corresponding input and output for each command.

GetActivityStats

Retrieves information about the activities that have been executed for a given process definition since the engine was started. The activity information is cumulative. A single activity name represents all executions of that activity.

The ExecutionTime computation for the Call Process Activity includes the sum of the execution times for all activities in the called process, not just the execution time for the call process activity itself.

Input Item	Datatype	Description
ProcessDefinitionName	String	Name of the process definition. Specifying a value for this element overrides the process definition specified on the Configuration tab.

 

Output Item	Datatype	Description
ProcessDefinitionName	String	Name of the process definition.
ActivityName	String	Name of the activity.
ActivityClass	String	Name of the class that implements the activity.
ExecutionCount	integer	Number of times the activity has been executed.
ElapsedTime	integer	Total clock time (in milliseconds) used by all executions of this activity. This includes waiting time for Sleep, Call Process, and Wait For... activities.
ExecutionTime	integer	Total clock time (in milliseconds) used by all executions of this activity. This does not include waiting time for Sleep, Call Process, and Wait For... activities.
ErrorCount	integer	Total number of executions of the activity that have returned an error.
LastReturnCode	String	Status code returned by most recent execution of this activity. This can be either OK, DEAD, or ERROR.
TracingEnabled	boolean	True if tracing is enabled for this activity, false if tracing is disabled.
MinElapsedTime	integer	Elapsed clock time (in milliseconds) of the activity execution that has completed in the shortest amount of elapsed time.
MaxElapsedTime	integer	Elapsed clock time (in milliseconds) of the activity execution that has completed in the longest amount of elapsed time.
MinExecutionTime	integer	Execution time (in milliseconds) of the activity execution that has completed in the shortest amount of execution time.
MaxExecutionTime	integer	Execution time (in milliseconds) of the activity execution that has completed in the longest amount of execution time.
MostRecentElapsedTime	integer	Elapsed clock time (in milliseconds) of the most recently completed activity execution.
MostRecentExecutionTime	integer	Execution time (in milliseconds) of the most recently completed activity execution.
TimeSinceLastUpdate	integer	Time (in milliseconds) since the statistics have been updated.
ExecutionCountSinceReset	integer	A comma-separated list of names of process definitions called by this activity.
CalledProcessDefs	String	Number of activity executions that have completed since the last reset of the statistics.

GetProcessDefinitionStats

Retrieves information about process definitions. I

Output Item	Datatype	Description
ProcessDefinitionName	String	Name of the process definition.
ProcessStarterName	String	Name of the process starter for the process.
NumberCreated	integer	Number of process instances created for this process definition.
NumberSuspended	integer	Number of times process instances have been suspended.
NumberSwappedToDisk	integer	Number of times process instances have been swapped to disk.
NumberQueued	integer	Number of times process instances have been queued for execution.
NumberAborted	integer	Number of times process instances have been aborted.
NumberCompleted	integer	Number of process instances that have been successfully completed.
NumberCheckpointed	integer	Number of times process instances have executed a checkpoint.
TotalExecutionTime	integer	Total execution time (in milliseconds) for all successfully completed process instances.
AverageExecutionTime	integer	Average execution time (in milliseconds) for all successfully completed process instances.
TotalElapsedTime	integer	Total elapsed time (in milliseconds) for all successfully completed process instances.
AverageElapsedTime	integer	Average elapsed clock time (in milliseconds) for all successfully completed process instances.
MinElapsedTime	integer	Elapsed clock time (in milliseconds) of the process instance that has completed in the shortest amount of elapsed time.
MaxElapsedTime	integer	Elapsed clock time (in milliseconds) of the process instance that has completed in the longest amount of elapsed time.
MinExecutionTime	integer	Execution time (in milliseconds) of the process instance that has completed in the shortest amount of execution time.
MaxExecutionTime	integer	Execution time (in milliseconds) of the process instance that has completed in the longest amount of execution time.
MostRecentExecutionTime	integer	Execution time (in milliseconds) of the most recently completed process instance.
MostRecentElapsedTime	integer	Elapsed clock time (in milliseconds) of the most recently completed process instance.
TimeSinceLastUpdate	integer	Time (in milliseconds) since the statistics have been updated.
NumberCompletedSinceReset	integer	Number of process instances that have completed since the last reset of the statistics.

GetProcessInstanceExceptions

Retrieves error information reported by the specified process.

Input Item	Datatype	Description
ProcessId	integer	ID for the process instance. If not specified, or if 0 is specified, exceptions for all process instances are returned.

 

 

Output Item	Datatype	Description
ExceptionSequenceNumber	integer	Sequence number of the exception, with the most recent exception first.
ProcessId	integer	ID for the process instance.
ExceptionMessage	String	Exception message.
StackTrace	String	Exception stack trace.
ExceptionClass	String	Exception class name.
ProcessStack	String	Process stack at exception. This displays the [ProcessName/GroupName/ActivityName] of the activity issuing the exception. If the activity is in a called sub-process, then the calling activity’s process stack plus a '>' separator character will be pre-pended to the normal information to produce the process stack of the activity issuing the exception.
TrackingID	integer	Tracking ID for the process instance.
ProcessDefinitionName	String	Name of the process definition.
State	String	State of the process.

GetProcessInstanceInfo

The values of the input elements for this command specify for which process instances you want to retrieve information. If you specify more than one input element, the values are treated as an AND condition. For example, If you specify the process definition name and the minimum duration, information for process instances for the specified process definition that meet the minimum duration time will be returned.

Input Item	Datatype	Description
ProcessId	integer	ID for the process instance.
ProcessDefinitionName	String	Name of the process definition used by the process instance. Specifying a value for this element overrides the process definition specified on the Configuration tab.
MinimumDuration	integer	Minimum time (in milliseconds) in elapsed clock time since the process instance started. All process instances with greater elapsed times will be retrieved.

 

Output Item	Datatype	Description
ProcessId	integer	ID for the process instance.
ProcessInstanceName	String	Name of the process definition used by the process instance.
TrackingId	String	Tracking ID for the process instance.
CustomId	String	Custom ID for the process instance.
Status	String	Status of the process.
StartTime	integer	Time (in milliseconds) when the process instance started.
ElapsedTimeSinceStarted	integer	Elapsed clock time (in milliseconds) since the process instance started.
MainProcessName	String	Name of the main process definition.
CurrentActivityName	String	Name of the currently executing activity in the process instance.
ProcessStarterName	String	Name of the process starter that started this process instance.
SubProcessName	String	Name of the process definition for the sub-process.

GetProcessStarterStats

Retrieves information about either active or inactive process starters. The information is cumulative. A single process starter name represents all executions of that process starter.

Output Item	Datatype	Description
ProcessDefinitionName	String	Name of the process definition.
ProcessStarterName	String	Name of the process starter.
Status	String	Status of the process starter. The status can be INACTIVE, ACTIVE, or READY.
TotalNumberCreated	integer	Number of process instances created by this process starter.
NumberCreatedPerHour	integer	Number of process instances per hour created by this process starter.
NumberRunning	integer	Number of process instances currently executing.
NumberCompleted	integer	Number of process instances that have completed.
StartTime	String	Time (in milliseconds) at which the process starter was started.
ElapsedTimeSinceStarted	integer	Elapsed clock time since the process starter was started.
RestartedFromCheckpoint	boolean	True if the process was restarted from a checkpoint.
TracingEnabled	boolean	True if tracing is enabled for this process starter, false if tracing is disabled.

GetRecoverableProcesses

Retrieves the process instances that can be recovered. See TIBCO ActiveMatrix BusinessWorks Administration for more information about recoverable process instances. Use the returned process ID in the RestartRecoverableProcess or RemoveRecoverableProces commands.

 

Output Item	Datatype	Description
ProcessId	integer	Process ID of the process instance that can be restarted.
Status	string	Status of the process instance. Can be one of the following: • faulted — this status occurs when the process instance is terminated due to an unhandled exception. • interrupted — this status occurs when the process instance is terminated due to engine failure (and the instance did not automatically restart when the engine restarted) or a manual termination.
TrackingId	string	Tracking ID for the process instance.
CustomId	string	Custom ID for the process instance.
ProcessDefinitionName	string	Process definition name for this process instance.
RestartActivityName	string	Name of the last executed Checkpoint activity in the process instance. This is the point at which the process instance will begin executing when it is restarted.

KillProcessInstance

Kills the specified process instance. The process instance is stopped immediately and permanently removed from the engine.

Input Item	Datatype	Description
ProcessId	integer	Process ID of the process instance you want to kill.

ListAllRoles

Returns a list of all roles, along with the current state (enabled or disabled) of each role.

Output Item	Datatype	Description
Role	string	Name of the role.
Enabled	boolean	True if the role is enabled, false if the role is disabled.

ListUserRoles

Returns a list of all user roles, along with the current state (enabled or disabled) of each role.

Output Item	Datatype	Description
Role	string	Name of the role.
Enabled	boolean	True if the role is enabled, false if the role is disabled.

RemoveRecoverableProcess

Removes the specified recoverable process instance from the list of potential recoverable processes. After executing this command, the checkpoint data of the specified process instance is removed and the process instance will no longer be able to be recovered. Obtain the process ID of the recoverable process with GetRecoverableProcesses the command.

Input Item	Datatype	Description
ProcessId	integer	The name or process ID of the process instance you want to remove.

RestartRecoverableProcess

Restarts the specified recoverable process instance. Obtain the process ID of the recoverable process with GetRecoverableProcesses the command.

Input Item	Datatype	Description
ProcessId	integer	The name or process ID of the process instance you want to restart.

ResumeProcessInstance

Resumes the specified process instance.

Input Item	Datatype	Description
ProcessId	integer	The name or process ID of the process instance you want to resume. You can retrieve the process ID for a process instance by using the GetProcessInstanceInfo command.

ResumeProcessStarter

Resumes the specified process starter.

Input Item	Datatype	Description
ProcessDefinitionName	string	The name of the process definition whose process starter you want to resume. Specifying a value for this element overrides the process definition specified on the Configuration tab.

StartStatsCollector

Enables collection of statistics for each executed activity. See TIBCO ActiveMatrix BusinessWorks Administrationfor more information about collecting activity statistics.

Output Item	Datatype	Description
FileName	string	Name of the file containing the collected data.

StopStatsCollector

Disables collection of statistics for each executed activity. See TIBCO ActiveMatrix BusinessWorks Administrationfor more information about collecting activity statistics.

Shutdown

Shuts down the process engine. If no input is provided, this command shuts down the engine immediately. You can optionally specify an amount of time to delay the shut down of the engine or you can specify that the engine should wait for any checkpointed process instances to complete before shutting down.

Input Item	Datatype	Description
MaxDelayInSeconds	integer	Specifies the amount of time (in seconds) to wait before shutting down the process engine.
WaitForCheckpoints	boolean	When true is specified, the engine waits for any checkpointed process instances to complete before shutting down.

 

SuspendProcessInstance

Suspends the specified process instance.

Input Item	Datatype	Description
ProcessId	integer	The name or process ID of the process instance to suspend. You can retrieve the process ID for a process instance by using the GetProcessInstanceInfo command.

SuspendProcessStarter

Suspends the specified process starter.

Input Item	Datatype	Description
ProcessDefinitionName	string	The name of the process definition whose process starter you want to suspend. Specifying a value for this element overrides the process definition specified on the Configuration tab.

 

Copyright © Cloud Software Group, Inc. All Rights Reserved