Using Console Commands

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

• User Confirmation
• Recovery of the Runtime Environment
• Cleanup for Audit Trail and Model Database
• Model Deployment to the Runtime Environment
• Configuration
• Obtaining Metrics
• Scoped Participants Management
• Explicit Binding and Un-binding of Events
• Daemon Management
• Migrating Document Repository
• Storing Preferences
• Multi-Model Environment
• Retrieving Model Version Tree Information

User Confirmation

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

• model deployment,
• cleanup and
• recovery

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 Stardust 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 Stardust 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 "2005-10-01"

or

-startBefore "2005-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"

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 Stardust 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 Stardust 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 Stardust 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:

• -overwrite
• -overwriteActive
• -overwriteVersion

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 Management View in the Administration Perspective.

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.

Using 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.

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.

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:

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

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:

• event daemon type: -name event.daemon
• timer trigger daemon type: -name timer.trigger
• mail trigger daemon tpye: -name mail.trigger
• notification daemon type: -name system.daemon
• prioritization daemon type: -name criticality.daemon

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:

• PARTITION
• REALM
• USER

The following are moduleId examples:

• configuration-variables
• permissions

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:
            ...