This chapter gives a detailed description of using specific commands and options:
If no -force parameter has been used in the command
line starting a batch, the tasks including
will always prompt for user confirmation.
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 "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:
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.
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.
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.
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-overwriteVersionThe configuration command allows to backup and upload
sources of partition configurations as a ZIP file.
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 Stardust Portal.
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>
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.
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. |
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
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. |
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
| 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. |
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
The -daemon option allows to perform operations
on a specified daemon.
The parameter -name defines which daemon is accessed,
including:
-name event.daemon-name timer.trigger-name mail.trigger-name system.daemon-name reporting.daemon-name criticality.daemon-name benchmark.daemon-name business_calendar.daemonAnother 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.
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
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
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.
The preferencesStore command allows backup and loading of
preferences as a ZIP file.
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:
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
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
The command migraterepository allows specifying
a batch size to limit the processing to short calls
via the optional parameters -batchSize and -timeLimit.
The parameter -batchSize specifies how many resources
are processed in one API call. The default value is 500.
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.
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
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.
In the following examples, Consumer1 is the model ID and Role1 is the element ID which makes a quaulified ID.
-u motu -p motu createuser -account "Test_user1" -addgrants {Consumer1}Role1
-u motu -p motu modifyuser -account "Test_user1" -addgrants {Consumer1}Role1
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:
...