Console

The Console command line tool handles administrative tasks related to a deployed model.

For a detailed description of the specific commands and options, refer to the next chapter Using Console Commands.

Scope

The Console command can perform the following tasks:

Setting Up the Environment

This section describes how to prepare your environment for using the Console command.

Start by downloading one of the Maven archetype templates from the Stardust artifactory matching your requirements. Refer to chapter Creating a Stardust Runtime Environment with Apache Maven in the Stardust Installation Guide for details.

Perform the following steps:

  1. Start a command console (cmd).
  2. Switch to your working environment, where you extracted the template.
  3. Add the client libraries of the application server you use.
  4. Add a database driver. Please refer to the specific database chapter in the Audit Trail Database Setup part of the Deployment Guide for information on the needed database driver.
  5. Additionally add the database connector jar file and other required model related jar files.
  6. Adapt the carnot.properties file, residing in your etc folder of your workspace environment.

For detailed information on setting up the environment for deployment, refer to chapter Deploying Stardust Components to an EJB Application Server of the Deployment Guide for EJB and to chapter Runtime Setup of the Spring Integration Guide for Spring accordingly.

Using Archetypes to create Environments for Console Clients

Stardust provides archetypes to create environments for console and sysconsole clients. Please refer to our Stardust Knowledge Base for details.

Global options

The global options for the Console tool are:

Option Short form Description
-domain   Identifies the target domain.
-realm   Identifies the realm to be used for user ID resolution.
-force -f Forces the command to execute without any callback.
-partition   Identifies the target partition.
-password <arg> -p The password of the user.
-user <arg> -u The user to login to the Stardust runtime.
-verbose -v Makes output more verbose.

Commands

The currently available commands are:

Command Description
bindeventhandler Provides explicit binding of events. Possible arguments:
  • -handler/-h - ID of the handler to bind.
  • -oid - OID for the instance(Activity or Process) specified by the type option.
  • -type/-t - type to which the event handler should bind to. Valid values are ai for an ActivityInstance or pi for a ProcessInstance.
cleanup Deletes the audit trail. Additional arguments are:
  • -audittrail/-a - deletes the audit trail.
  • -keepUsers/-k - keeps users and their roles.
  • -model/-m <arg> - deletes audit trail for the model with the specified OID
  • -models/-s - deletes all deployed models too.
createdepartment Creates a department. Arguments:
  • -name/-n <arg> -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.
  • -description/-d <arg> - an optional description of the department.
  • -departmentpath/-dp <arg> - path to the department(each department is separated by a '/').
  • -recursive/-r - if specified, all departments specified in the path will be created(if missing). By default, it is set to false.
  • -participantid/-pid <arg> -id of the participant(role or organization).
createuser Creates a Stardust user. Possible arguments:
  • -account/-a <arg> - account name of the user.
  • -description/-d <arg> - an optional description of the user.
  • -email/-e <arg> - e-mail address of the user.
  • -firstname/-f <arg> - first name of the user.
  • -grants/-g <arg> - grants given to the user. Specify as comma-separated list of participant IDs. Model version constraints can be given with the format id:modeloid, e.g. engineer:47,clerk.
  • -lastname/-l <arg> - last name of the user.
  • -password/-p <arg> - the password of the user.
  • -realm - identifies the realm to be used for user ID resolution.
  • -validfrom/-v <arg> - Valid from time of the user.
  • -validto/-t <arg> - Valid to time of the user.

Note
In case of multi-model environment, if participant IDs are duplicated in more than one models then qualified IDs of participants should be supplied despite of their IDs. Qualified ID is comprised of model ID and participant ID ({modelID}participantID). Administrator role is not bounded with this restriction because it is merged into a single administrator from all the deployed model.

configuration Allows backup and loading of partition configuration as a ZIP file. Possible arguments:
  • -backup - extracts all files stored in the configuration area of the logged in user's partition or the system(default) configuration files to be stored in a ZIP file.
  • -targetFile filename - the target file where the ZIP will be stored.
  • -load - uploads all configuration files from the ZIP archive.
  • -sourceFile filename - the source file of the ZIP archive.
  • -scope partition|system|all - the scope for the configuration operation. The default scope is partition.
  • -ignoreEmptyFolders - ignores empty folders for the backup and load operation.
daemon Manages a daemon. Valid arguments are:
  • -ack/-c - executes a daemon command with acknowledgment.
  • -list/-l - lists all daemons.
  • -name/-n <arg> - the name of the daemon.
  • -start/-a - starts the daemon
  • -status/-s - shows the daemon state.
  • -stop/-z - stops the daemon.
dashboard Prints Audit Trail Database metrics
  • -overview, -o - evaluates some overall indicators (default option).
  • -recovery, -r - evaluates process recovery related indicators
  • -recovery -showOids - using option showOids in combination with recovery shows a list of process instances OIDs in place of only the count of process instances
delete Deletes a model from the audit trail. Use the following argument:
  • -model/-m modeloid - model with OID modeloid.
deletedepartment Deletes a department. Possible arguments:
  • -departmentpath/-dp <arg> - path to the department(each department is separated by a '/').
  • -recursive/-r - if specified, all departments specified in the path will be deleted. By default, it is set to false.
  • -participantid/-pid <arg> -id of the participant(role or organization).
deploy Deploys a model. It accepts the arguments:
  • -comment/-c <arg> - adds a deployment comment.
  • -deployVersion - If set the given model will only be deployed if no existing deployment of a model having the same ID and version exists.
    This option may be used in combination with the -overwriteVersion option.
  • -filename/-n <arg> - the file to be deployed. Also ZIP archives containing a set of XPDL model files are possible.
  • -ignoreWarnings/-w - if set, a deployment is done even in case of warnings.
  • -overwrite/-o <arg> - if set, the specified model will be overwritten. Not supported in case the file to be deployed is a deployment unit archive.
  • -overwriteActive/-a - if set, the active model will be overwritten. Not supported in case the file to be deployed is a deployment unit archive.
  • -overwriteVersion - if set an existing deployment of the model having the same ID and version as the model to be deployed will be overwritten. Not supported in case the file to be deployed is a deployment unit archive.
  • -partition <ID[,ID]*> - identifies the partition(s) to operate against. If multiple partitions are specified, model deployment will either be successfully performed against all given partitions or fail completely.
  • -validfrom, -f <arg> - Valid from time of the deployment.
encrypt Encrypts the password passed and returns the encrypted password string to the console. Use the following argument:
  • password <arg> - the password to be encrypted.
  • passfile <arg> - If this parameter is set, <arg> is expected to contain a file path to a file. This file will be loaded and expected to conatin an encrypted password string prevoiously created with the command "encrypt -password <arg>" . This String will be decrypted and then used for authentication. If the property "-passfile" is used, a "-password" option simultaneously passed will be ignored.
engine Flushes all internal caches, effectively returning the engine to a state just like after it has started. Use the following argument:
  • init - starts the flushing
list Lists the models in the audit trail.
  • -deployments/-d - lists deployed model versions.
  • -allVersions/-a - lists all deployed model versions and their relationships to other models.
  • -model/-m <arg> - lists the deployment information for a specific model id.
  • -short/-s - using this option results in leaving out detailed information concerning the linking.
  • -verbose/-v - using this option shows inactive implementation relations as well.
migraterepository Option to specify a batch size to limit the processing to short calls:
  • -batchSize / -b - specifies how many resources are processed in one API call. The default value is 500.
  • -timeLimit / -t - allows setting a time limit in minutes after which the migration is stopped after finishing the current batch. Default for this parameter is 0 which means no time limit is set and the migration process continues until it is complete.
modifyuser Modifies a Stardust user. The following arguments may be used:
  • -account/-a <arg> - account name of the user.
  • -addgrants/-g <arg> - grants to be given to the user. Specify as comma separated list of participant IDs. Department constraints can be given with the format id@departmentoid, e.g. engineer@33,clerk or as id@departmentpath e.g. engineer@root/child,clerk. Model version constraints can be given with the format id:modeloid, e.g. engineer:47,clerk.
  • -description/-d <arg> - an optional description of the user.
  • -email/-e <arg> - e-mail address of the user.
  • -firstname/-f <arg> - first name of the user.
  • -lastname/-l <arg> - last name of the user.
  • -newaccount/-n <arg> - the new account of the user, in case it should be changed.
  • -password/-p <arg> - the password of the user.
  • -realm - identifies the realm to be used for user ID resolution.
  • -removegrants/-r <arg> - grants to be removed from the user. Specify as comma separated list of participant IDs. Model version constraints can be given with the format id:modeloid, e.g. engineer:47,clerk.
  • -validfrom/-v <arg> - Valid from time of the user.
  • -validto/-t <arg> - Valid to time of the user.

Note
In case of multi-model environment, if participant IDs are duplicated in more than one models then qualified IDs of participants should be supplied despite of their IDs. Qualified ID is comprised of model ID and participant ID ({modelID}participantID). Administrator role is not bounded with this restriction because it is merged into a single administrator from all the deployed model.

preferenceStore command to backup and load preferences as a ZIP file:
  • -backup -targetFile targetfile - extracts all preferences stored in the PreferenceStore.
    • -targetFile - path to the target ZIP file which will contain the preferences.
    • -limitScope - Limits operation to the specified scope. The default is all scopes. Available scopes are PARTITION, REALM or USER.
  • -limitModuleId - Limits operation to the specified moduleId. The default is preferences having any moduleId. Any one moduleId can be specified. The * wildcard can also be used.
  • -load -sourceFile sourcefile - uploads all preferences from the ZIP archive
    • -sourceFile - the ZIP file containing the preferences.
realm Creates, drops and lists realms:
  • -create ID - creates a new realm with the given ID, if no realm having this ID currently exists. Scope is the partition the user is logged in.
  • -drop ID - deletes the realm identified by the given ID, if no user associated with this realm exists.
  • -list - lists all existing realms in scope of the target partition.
recover Recovers process instances. The following arguments can be used:
  • -all/-a - recovers all process instances of the audit trail.
  • -batchSize <arg> - Performs recovery of process instances in controlled batches. If this option is missing, all qualifying process instances are recovered in one big transaction.
    Might be used for both full and quick recovery.
  • -max/-m <arg> - Recovers at most the given number of process instances. Might be used for both full and quick recovery.
  • -processes/-p <arg> - recovers selected process instances, specified as a comma separated list of OIDs.
  • -quick <arg> - Performs a quick recovery of the audit trail, which effectively just considers INTERRUPTED process instances.
  • -startedAfter <arg>/-startedBefore <arg> - Recovers only process instances started after/before the given date. Might be used for both full and quick recovery. The specified date must conforms to ISO date patterns (i.e. "2013-10-01","2013-10-01 08:30" or "2013-01-01T08:30:00:000").
setPrimaryImplementation Sets the primary implementation. The following arguments are possible:
  • -interfaceModelOid/-moid <arg> - model OID of interface.
  • -processId/-ipid <arg> - process ID
  • -implementationModelId/-imid <arg> - implementation model ID.
  • -comment/-c <arg> - adds a comment.
unbindeventhandler Provides explicit unbinding of events. Possible arguments:
  • -handler/-h - ID of the handler to unbind.
  • -oid - OID for the instance(Activity or Process) specified by the type option.
  • -type/-t - type for which the eventhandler should unbind from. Valid value are ai for an ActivityInstance or pi for a ProcessInstance.
version Returns version information for the Stardust Process engine. Option:
  • -component <arg> - specifies which components the version information should be retrieved for. Supported components:
    • engine - retrieves version information for the engine. Return format: Stardust engine version: x.x.x.x
    • client - retrieves version information for the client VM itself. Returns for example the behavior of the command in earlier Stardust versions.
    • all - retrieves version information for engine and client components in two separate lines. Default value to be applied if no option is set.

Please refer to the next chapter for a detailed description of the specific commands and options.