Using the Console Command

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 Console Command Use Cases.

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 Infinity Process Platform artifactory matching your requirements. Please refer to chapter Creating a Runtime Environment with Apache Maven in the Installation Guide section Maven Archetypes of our Infinity Process Platform Wiki Maven/Basic Setup page for details on how to retrieve these configurations.

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 Infinity Process Platform 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.

Note
If you are running the console command line tool directly against IPP's database, you need to add the following missing property to your client side carnot.properties file to bypass the password history update:
Security.LoginUsersWithoutTimestamp = *

Using Archetypes to create Environments for Console Clients

Infinity provides archetypes to create environments for console and sysconsole clients. Please refer to chapter Creating a Runtime Environment with Apache Maven in the Installation Guide section Stardust Archetypes of our Infinity Process Platform Wiki Maven/Basic Setup page 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 Infinity Process Platform runtime.
-verbose -v Makes output more verbose.

Commands

The currently available commands are:

Command Description
abort
  • -activityInstance/-ai - a single AI OID or a comma separated list of AI OIDs (without spaces). Required if no -pi is set.
  • -processInstance/-pi - a single PI OID or a comma separated list of PI OIDs (without spaces). Required if no -ai is set.
  • -scope/-sc - eiher root or sub as parameter
  • -info/-i - This is an optional parameter. Added as Note to each aborted PI, if more than one single word quotes must be used.
Example - console -u motu -p motu abort -sc root -ai 5,8,20 -i "Aborted by Console Command"
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 Infinity Process Platform 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
export

Exports audit trail information.

Note
This feature is customer technology preview only. It may not be functionally complete and is not intended for production use.

The following arguments are available:
  • -batchSize <arg> - defines the number of process instances to be exported per batch. Defaults to 1000.
  • -concurrentBatches <arg> - defines how many batches can export concurrently. Defaults to 10.
  • -partition - Optionally specifies the partition(s) the operation should be run against. Defaults to the default partition. Accepts as argument a single partition ID or a comma separated list of partition IDs.
  • -archive - default. Delete data from the Audit Trail database.
  • -dump, -d <arg> - optional. Dumps all process instances (terminated and active) to the specified archive location.
  • -withDocuments, -wd <arg> (latest/all) - optional parameter determines if documents are exported too. Per default no documents are exported. Valid options are: NONE/LATEST/ALL.
Arguments for filtering with no combination allowed are the following:
  • -modelOids <OID[,OID]*> - all process instances for the models specified by the models OIDs provided (comma separated list of OIDs). Process instances must be terminated (completed or aborted).
  • -models, -model <ID[,ID]*> - all process instances of a model with given ID (comma separated list of IDs). Process instances must be terminated (completed or aborted).
  • -processOids <OID[,OID]*>/<OID-OID> - all process instances with given OID defined via a comma separated list of OIDs or a range, e.g.: 1-1000. Note that process instances must be terminated (completed or aborted).

If none of the above filters are specified, all process instances of all models and version for the given partition are exported.

Arguments for filtering with combination allowed are the following:
  • -processes, -procDef <ID[,ID]*> - all process instances of process definition with given IDs (comma separated list). Process instances must be terminated (completed or aborted).
  • -toDate, -td <timestamp> - all process instances terminated at toDate or before if the use case is archive. All process instances started at toDate or before if the use case is dump.
  • -fromDate, -fd <timestamp> / <t1> -toData <t2> - Restricts any operation to process instances started after the given date (always inclusive). The specified date must conforms to ISO date patterns.
  • -dateDescriptors, -ddscr <arg> - Restricts any operation to process instances that has the specified descriptor values. Use this option to specify descriptors that have date values. The specified date must conforms to ISO date patterns.
  • -descriptors, -dscr <ID=VALUE[,ID=VALUE]*> - Restricts any operation to process instances that has the descriptor values. Use this option to specify all non-date descriptors. If more are specified as comma separated list, the filtering is done with AND conjunction.
These filters need to be applied if available.

For details and example usage of the export command please refer to chapter Importing and Exporting Audit Trail Information - Technology Preview.

import

Imports audit trail information.

Note
This feature is customer technology preview only. It may not be functionally complete and is not intended for production use.

The following arguments are available:
  • -partition - Optionally specifies the partition(s) to be imported into. Accepts as argument a single partition ID or a comma separated list of partition IDs. If this parameter is not used, the import command of sysconsole has an effect only on the default partition.
  • -concurrentBatches <arg> - defines how many batches can export concurrently, defaults to 10.
  • -withDocuments, -wd <arg> (latest/all) -optional parameter determines if documents are imported too. Per default no documents are exported. Valid options are: NONE/LATEST/ALL.
  • -preferences <arg> - optional parameter pointing to a preferences.xml that contains information about the archive/dump where the data is imported from.
Arguments for filtering with no combination allowed are the following:
  • -models, -model <ID[,ID]*> - Imports all process instances for specified list of model IDs (comma separated list of IDs).
  • -processOids <OID[,OID]*> - all process instances with given OID.
  • -processOids <OID-OID> - all process instances for given range.
Arguments for filtering with combination allowed are the following:
  • -processes, -procDef <ID[,ID]*> - Imports all process instances for a specified list of process definition IDs (comma separated list of IDs).
  • -toDate, -td <timestamp> - all process instances started at toDate or before.
  • -fromDate, -fd <timestamp> / <t1> -toData <t2> - Restricts import to process instances started after the given date (always inclusive). The specified date must conforms to ISO date patterns.
  • -dateDescriptors, -ddscr <arg> - Restricts any operation to process instances that has the specified descriptor values. Use this option to specify descriptors that have date values. The specified date must conforms to ISO date patterns.
  • descriptors, -dscr <ID=VALUE[,ID=VALUE]*> - Restricts any operation to process instances that has the descriptor values. Use this option to specify all non-date descriptors. If more are specified as comma separated list the filtering is done with AND conjunction.

For details and example usage of the import command please refer to chapter Importing and Exporting Audit Trail Information - Technology Preview.

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 Infinity Process Platform 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.
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 Infinity 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: Infinity Process Platform 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 Infinity Process Platform 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.