Console Command Use Cases

This chapter gives a detailed description of using specific commands and options:

User Confirmation

If no -force parameter has been used in the command line starting a batch, the tasks including

will always prompt for user confirmation.

Recovery of the Runtime Environment

In certain cases (for example, if an EJB server crashes, or there is an execution exception), non-interactive activities may be left in an uncompleted state. To "reanimate" these non-interactive activities you can invoke the Infinity Process Engine recovery using the command line

   > console -user motu -password motu recover

where the user and password are valid entries for an administrator role defined in the deployed workflow model.

Use the -force flag to omit the user confirmation and to ignore messages on recovery already in progress.

With the -all flag, all recoverable process instances are recovered.

The flag -batchSize <number> is used to specify the number of instances recovered in one database transaction. If this option is missing, all qualifying process instances are recovered in one big transaction. The flag -batchSize <number> might be useful to limit the usage of database resources, e.g. rollback files. This flag does not limit or filter the number of process instances to be recovered.

With the -max <number> or -m <number> flag you can limit the number of process instances to be recovered. The console will return after this limit is reached independently of remaining process instances to be recovered.

The -quick flag restricts the recovery only to process instances in the INTERRUPTED state. For these process instances, the Infinity Process Engine has detected an unhandled exception during execution of one of the associated non-interactive activities and has explicitly marked the process to be interrupted. This flag can be used in combination with the other filter flags.

The -startedAfter <timestamp> and/or -startedBefore <timestamp> flags can be used to select the process instances to be recovered by their start timestamp. Hereby, the specified date must conforms to ISO date pattern e.g.

-startAfter "2013-10-01"

or

-startBefore "2013-10-01 08:30"

or

-startAfter "2006-01-01T08:30:00:000"

Specific process instances can be recovered using the -processes <oid list> or -p <oid list> flag. <oid list> has to be a comma separated list with process instance OIDs, e.g.

-process "192999812, 12766767, 1873788"

Upgrade might fail in theory. For example, if there is a power outage, or network problem during upgrading. As a result the database might be inconsistent, with some steps committed and some not.

In that case, once the problem that caused the upgrade to fail was resolved, it is recommended to start the upgrade again with "-recover" option that will perform special steps to ensure database consistency. So, the basic rule is:

Cleanup for Audit Trail and Model Database

The audit trail database stores all information on every piece of work that has been performed via the Infinity Process Engine. Also, it stores the workflow model information, on the base of which processes are instantiated and their activities performed. The administrator has full control over the database, so that both the audit trail and the model information can be deleted.

Cleaning up audit trail database means deleting all the audit trail data but the definition of tables in the database remains untouched. All the log entries and all users defined in the Infinity Process Platform runtime environment are also deleted. Cleaning up model database will delete the model information from the database also deleting all data contained in the audit trail.

Cleanup should never be applied to models in production!

Also, it is necessary to restart the EJB server after you have performed a cleanup.

To clean up only the audit trail invoke the clean-up batch using the command line:

> console -user motu -password motu cleanup -audittrail

To remove both the audit trail and all the models from the database invoke the cleanup batch using the command line:

> console -user motu -password motu cleanup -audittrail -models

Use -force flag not to be prompted for additional confirmation to perform this task.

Model Deployment to the Runtime Environment

The command line utility is also intended to be used for deploying a Infinity Process Platform workflow model to the runtime environment. The console command for model deployment is deploy.

There are two choices, to deploy from a file or to directly deploy from a process model repository.

Deployment of a file is done by calling the console like:

> console -user <username> -password <password> deploy -filename <model file> <other-options>

You can force a deployment even in case of warnings being issued by using the option -ignoreWarnings. Deployments with errors are never performed.

Overwriting Options

You can deploy in overwrite mode by using the option -overwrite <OID>, where OID represents the OID of the model version to be overwritten. To overwrite the active model, use -overwriteActive option.

To overwrite an existing deployment of the model having the same ID and version as the model to be deployed, use the -overwriteVersion option.

Note that all overwrite options are not supported in case the file to be deployed is a deployment unit archive.

Deployments of Deployment Unit Archives

The console command -deploy also accepts ZIP archives containing a set of XPDL model files as target files for the argument -filename. Note that if the file to be deployed is a deployment unit archive, the following options cannot be used:

Configuration

The configuration command allows to backup and upload sources of partition configurations as a ZIP file.

Backup

The -backup option extracts all files stored in the configuration area of the logged-in user's partition or the default system configuration files and adds them to a .zip file stored at a target file specified by the -targetFile option.

configuration -backup -targetFile <filename>

The extracted file structure represents the structure of the tree view for the Resource Manager View in the Administration Perspective of the Infinity Portal.

Upload

The -load option uploads all configuration files from the ZIP archive given with the -sourceFile parameter. This command will replace an entire configuration. All files of the old configuration are removed.

configuration -load -sourceFile <filename>

Further options

The -scope option defines the scope for the configuration operations. The default scope is partition. Momentarily other scopes are not possible.

Both, the -backup and the -load option backup and load empty folders respectively. This can be switched off by using the option -ignoreEmptyFolders.

Obtaining Metrics

Metrics of the audit trail database to be used for administrative purposes can be obtained via the dashboard command.

With the -overview option general metrics (e.g. number of active/suspended/interrupted activities or number of active users) can be obtained.

The -recovery option displays metrics to estimate the effect of recovery operations.

E.g. the operation

> console dashboard -overview -recovery

will cause the following output:

Overview

Processes (total): 600
Processes (alive): 100
Processes (completed): 500
Processes (aborted): 0

Activities (total): 1,200
Activities (alive): 100
Activities (completed): 1,100
Activities (aborted): 0

Users (total): 21
Users (active): 21


Process Recovery Indicators

Interrupted process instances: 0
Interrupted activity instances: 0

Number of process instances likely to have ..
.. pending process completion: 0
.. pending process abortion: 0
.. crashed activity instances: 0
.. crashed activity threads: 0

The following table contains a short explanation of all displayed metrics.

Metric Interpretation
Processes (total) Total number of processes
Processes (alive) Number of alive process instances. Alive means not being in states ABORTED or COMPLETED.
Processes (completed) Number of completed processes
Processes (aborted) Number of aborted process instances
Activities (total) Total number of activities
Activities (alive) Number of alive activity instances. Alive means not being in states ABORTED or COMPLETED.
Activities (completed) Number of completed activities
Activities (aborted) Number of aborted activities
Users (total) Total number of users
Users (active) Total number of valid users
Interrupted process instances Number of process instances for those at least one interrupted activity exists.
Interrupted activity instances Number (non-interactive) activity instances interrupted via non-declarative exceptions thrown by the invoked application. These applications are retried during recovery.
Number of process instances lacking completion Number of process instances not having further pending activities, but not being marked as COMPLETED, ABORTING or ABORTED themselves. Performing a process recovery on such processes is recommended.
The number is based on all process instances from the audit trail that are not in the state COMPLETED, ABORTING or ABORTED and are having unconsumed transition tokens
Number of process instances lacking abortion Number of process instances in state ABORTING. These process instances had been scheduled for abortion but did not succeed. Performing a process recovery on such processes is recommended.
The number is based on all process instances from the audit trail that are in the state ABORTING.
Number of activity instances lacking abortion Number of activity instances in state ABORTING. These activity instances had been scheduled for abortion but did not succeed. Performing a process recovery on such activities is recommended.
The number is based on all activity instances from the audit trail that are in the state ABORTING.
Number of process instances having crashed activities Number of process instances (not being marked as ABORTED or COMPLETED) whose activities have obtained exceptions during execution (activity state INTERRUPTED or CREATED). Performing a process recovery on such processes is recommended.
The number is based on all process instances from the audit trail that are not in the state COMPLETED or ABORTED, having unconsumed transition tokens and having activities that are in the state CREATED or INTERRUPTED targeted by the transition token.
Number of process instances having crashed event bindings Gets the number of process instances having crashed event bindings. Performing a process recovery on such processes is recommended.
The number is based on all event binding from the audit trail having a deactivate flag on the event type id.
Number of process instances having crashed threads Number of process instances that are not in the state COMPLETED or ABORTED and where the target activity instances of transitions are 0 for all referenced source activity instances.
The number is based on all process instances from the audit trail that that are not in the state COMPLETED or ABORTED and where all target activity instances for all existing source activity instances are 0.

Displaying Audit Trail Metrics with Process OIDs List

If you like to have a list of process instances OIDs shown in place of only the count of process instances, use the option showOids in combination with dashboard -recovery. All of these process instances are candidates for recovery.

console dashboard -recovery -showOids

Here is an example with a list of process instances OIDs likely to have:

.. pending process completion: 25, 26
.. pending process abortion: 4, 6, 9
.. pending activity abortion: 3, 8
.. crashed activity instances: 16, 2, 18, 20, 22, 24, 12, 28, 14, 30
.. crashed activity threads: none

Scoped Participants Management

Following are the commands supported for scoped participants:

Command Type Short Name Long Name Required Description
createdepartment local n name false The name of the department to be created - if not supplied, the id will be taken as name. By default, the ID of the department is taken.
createdepartment local d description false The description of the department to create.
createdepartment local dp departmentpath true The path to the department(each department is separated by a '/').
createdepartment local r recursive false If specified, all departments specified in the path will be created(if missing). By default, it is set to false.
createdepartment local pid participantid true The id of the participant(role or organization).
deletedepartment local dp departmentpath true The path to the department(each department is separated by a '/').
deletedepartment local r recursive false If specified, all departments specified in the path will be deleted. By default, it is set to false.
deletedepartment local pid participantid true The id of the participant(role or organization).
modifyuser local g addgrants false Grants to be given to the user. Specified as comma separated list of participant IDs. Department constraints can be added with @%OID_OR_PATH% where %OID_OR_PATH% can be either an OID or a path(each department in the path is separated by a '/'). For example, engineer@33 or engineer@department1/department2
modifyuser local r removegrants false Grants to be removed from the user. Specified as comma separated list of participant IDs. Department constraints can be added with @%OID_OR_PATH% where %OID_OR_PATH% can be either an OID or a path(each department in the path is separated by a '/'). For example, engineer@33 or engineer@department1/department2
createuser local g addgrants false Grants to be given to the user. Specified as comma separated list of participant IDs. Department constraints can be added with @%OID_OR_PATH% where %OID_OR_PATH% can be either an OID or a path(each department in the path is separated by a '/'). For example, engineer@33 or engineer@department1/department2.
createuser local r removegrants false Grants to be removed from the user. Specified as comma separated list of participant IDs. Department constraints can be added with @%OID_OR_PATH% where %OID_OR_PATH% can be either an OID or a path(each department in the path is separated by a '/'). For example, engineer@33 or engineer@department1/department2.

Example Commands for Scoped Participants

All commands have local and global options. The user and password are global options that means they have to be provided before the command name. For example, console -u motu -p motu createdepartment. The parameters u and p are provided before the command createdepartment. In case of local option, the parameters are specified after the command. For example, deletedepartment -pid SubSubChildOrg -dp m1/m2/m3 -r. The parameters pid and dp are local parameters because they are command specific and coming after the command. Following are example commands for scoped participants:

To create the department using the command line:

> console -u motu -p motu createdepartment -pid SubSubChildOrg -dp m1/m2/m3 -r

To delete the department using the command line:

> console -u motu -p motu deletedepartment -pid SubSubChildOrg -dp m1/m2/m3 -r

To create the user using the command line:

> console -u motu -p motu createuser -a mynewuserwithgrant -password mypassword -g SubSubChildOrg@m1/m2/m3

To modify the user using the command line:

> console -u motu -p motu modifyuser -a motu -g SubSubChildOrg@m1/m2/m3

Explicit Binding and Unbinding of Events

Command Short Name Long Name Required Description
bindeventhandler h handler true ID of the handler to bind
bindeventhandler OID OID true The OID for the instance(Activity or Process) specified by the type option.
bindeventhandler t type true The type to which the eventhandler should bind to. Valid values are ai for an ActivityInstance or pi for a ProcessInstance.
unbindeventhandler h handler true ID of the handler to unbind
unbindeventhandler OID OID true The OID for the instance(Activity or Process) specified by the type option.
unbindeventhandler t type true The type for which the eventhandler should unbind from. Valid values are ai for an ActivityInstance or pi for a ProcessInstance.

Example Commands for Binding and Unbinding Events

bindeventhandler

> console -u motu -p motu bindeventhandler -t ai -oid 5 -h myHandler

unbindeventhandler

> console -u motu -p motu unbindeventhandler -t ai -oid 5 -h myHandler

Daemon Management

The -daemon option allows to perform operations on a specified daemon. The parameter -name defines which daemon is accessed, including:

Another parameter including -start, -stop or -status defines which operation should be performed on the selected daemon. Next to these parameters the username and password of an Administrator must be passed to the console as well. You can start the event handling daemon with the command:

> console.bat -user motu -password motu daemon -name event.daemon -start

For general information on working with daemons, refer to chapter Daemons in the Administrative Concepts section of the Concepts part.

Monitoring the State of a Daemon

To query the status of a daemon, you use the console tool with the command daemon and specify the name of the daemon and the action to perform (-status). Use the appropriate user and password for your system, our examples are written for user motu with password motu.

> console.bat -user motu -password motu daemon -name mail.trigger -status

Starting and stopping a Daemon

To start or stop a daemon, you use the console tool exactly as for getting its status, except that the command used is -start for starting the daemon, respectively -stop for stopping the daemon. An example is provided below.

> console.bat -user motu -password motu daemon -name timer.trigger -start
> console.bat -user motu -password motu daemon -name event.daemon -stop  

Acknowledgment

To start a daemon with acknowledgment, use the option -ack/-c. If a daemon is started with acknowledgment, each new request first checks that previous requests have been acknowledged and are not still in response-requested state. When started without acknowledgment, these checks will not be made.

Storing Preferences

The preferencesStore command allows backup and loading of preferences as a ZIP file.

Extracting Preferences

To extracts all preferences stored in the PreferenceStore, use the option -backup. The -targetfile argument should provide the path to the target ZIP file which will contain the preferences. The preferences will be dumped in a .ZIP file stored at the target file. Optionally, you can set an option -limitScope and -limitModuleId to change the scope of the specified moduleID preferences. The following scope options are possible:

The following are moduleId examples:

The default scope is all for -limitScope. For -moduleId the default is preferences having any moduleId.

Examples:

-user motu -password motu preferenceStore -backup -targetFile c:/tmp/tst.zip -limitScope USER -limitModuleId ipp-portal-common
-user motu -password motu preferenceStore -backup -targetFile c:/tmp/tst.zip -limitScope USER -limitModuleId ipp-portal*
-user motu -password motu preferenceStore -backup -targetFile c:/tmp/tst.zip -limitScope PARTITION -limitModuleId bcc
-user motu -password motu preferenceStore -backup -targetFile c:/tmp/tst.zip -limitScope PARTITION -limitModuleId permissions
-user motu -password motu preferenceStore -backup -targetFile c:/tmp/tst.zip -limitScope PARTITION -limitModuleId configuration-variables

Loading Preferences

To upload all preferences from a ZIP archive, use the option -load. The argument -sourcefile should describe the ZIP file containing the preferences. It is assumed that the structure of the ZIP archive reflects the structure of a result of the -backup operation. You have to restart your server to make the imported variable value effective. Note that the load option replaces existing preferences if they are already contained in the source ZIP file.

Example:

preferenceStore -load -sourceFile c:/tmp/test.zip

Migrating Document Repository

The command migraterepository allows specifying a batch size to limit the processing to short calls via the optional parameters -batchSize and -timeLimit.

Batch Size

The parameter -batchSize specifies how many resources are processed in one API call. The default value is 500.

Time Limit

The parameter -timeLimit allows setting a time limit in minutes after which the migration is stopped after completing the current batch. The migration to the new repository version might not be complete but the repository is still consistent and the migration can be continued by using the console command again at a later point in time. The default value for this parameter is 0, which means no time limit is set and the migration process continues until it is complete.

Example

An example command for setting a migration for a maximum of two hours with a batch size of 300 would look like the following:

console -f -u motu -p motu migraterepository -batchSize 300 -timeLimit 120

Multi-Model Environment

In all methods referring to top model elements via ID, the qualified ID of the model element can be used. The qualified ID is defined as:

'{' + model-id + '}' + element-id

If participants have duplicate IDs in multi-model environment then qualified ID should be used to execute the createuser and modifyuser commands.

Example Command for Multi-Model Environment

In the following examples, Consumer1 is the model ID and Role1 is the element ID which makes a quaulified ID.

Create User Example

-u motu -p motu createuser -account "Test_user1" -addgrants {Consumer1}Role1

Modify User example:

-u motu -p motu modifyuser -account "Test_user1" -addgrants {Consumer1}Role1

Retrieving Model Version Tree Information

The console command -list can be used to display all model versions deployed. The model versions are displayed in the following structure:

ModelA
      ModelA - Version 2 (oid: nnn) (active)
         Provider relationships for model elements used by other models:
            used by ModelB - Version 3 (oid:mno)
            used by ModelC - Version 3 (oid:mnp)
            ...
         Consumer relationships for model elements provided by other models
            using ModelD - Version 1 (oid:mnq)
         Provided Process Interfaces
            Process Interface1
               implemented by ModelA - Version 2 (oid: nnn) (Default)
               implemented by ModelE - Version2 (oid:nmo)
               implemented by ModelF - Version2 (oid:nmp) (Primary Implementation)
               ...
            ...
   ModelB - Version1 (oid:mmm)
         Referenced By:
            ...

By default, the above tree will only contain the active versions of every model. Other versions can be included by supplying the following parameter:

console -list -allVersions

The option -model takes the model id (String) as a parameter and only displays the subtree for this model Id, e.g.:

console -list -model DemoModel

To display the model and model version nodes only, but skip the linkage information, use the -short option:

console -list -short

In case you like to have also inactive implements relationships displayed, which, although not relevant for newly started processes, might be relevant for running intances, use option -verbose. They will be marked as "usage inactive".

console -list -verbose

For example, the structure could look like the following:

   ModelA
      ModelA - Version 2 (oid: nnn) (active)
         Provider relationships for model elements used by other models:
            used by ModelB - Version 3 (oid:mno)
            used by ModelC - Version 3 (oid:mnp)
            ...
         Consumer relationships for model elements provided by other models
            using ModelD - Version 1 (oid:mnq)
         Provided Process Interfaces
            Process Interface1
               implemented by ModelA - Version 2 (oid: nnn) (Default)
               implemented by ModelE - Version2  (oid:nmo)
               implemented by ModelE - Version1  (oid:nop)   - usage inactive
               implemented by ModelF - Version2  (oid:nmp)  (Primary Implementation)
               implemented by ModelF - Version1  (oid:nmq)  (Primary Implementation) - usage inactive
               ...
            ...
   ModelB - Version1 (oid:mmm)
         Referenced By:
            ...