Contents of this section:

List Running Workflow Execution Instances

To list the workflows running in a Qorus instance, the omq.system.get-workflow-info() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server. The ostatus: Show System, Workflow, and Service Status program provides a user-friendly command-line interface to this method, for example:

unixprompt% ostatus -w

The output should look as follows (actual output will depend on instance parameters and which workflows have been started – also the output has been truncated for formatting purposes):

Qorus 3.0.4.p7 psft-sit-av2s329t-1 sessionid 352
workflows:
 W    1 ACTIVATE-ACCOUNT          1.0   NORMAL         768/ 2 itera... 
 W    2 ACTIVATE-CUSTOMER         1.0   NORMAL         671/ 2 itera...
 W    3 ACTIVATE-RESERVED-NUMBERS 1.0   NORMAL           0/ 2 itera...
 W    4 COLL-PSFT-BRIDGE          1.0   NORMAL        1416/ 2 itera...
 W    5 DEACTIVATE-SUBSCRIBER     1.0   NORMAL         161/ 2 itera...
 W    6 MAINTAIN-CUSTOMER         1.0   NORMAL          19/ 1 itera...

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Start a Workflow Execution Instance

To start an execution instance of a Qorus workfow, the name, version, and mode are required parameters to the omq.system.start-workflow() API method. Furthermore, workflow execution instance options can be given.

To start a workflow execution instance, enter the following at the command line:

unixprompt% ostart <workflowname> [version] [mode]

If the mode parameter is present, it must be one of the following:

NORMAL: the workflow execution instance will start processing new orders (corresponds to OMQ::WM_Normal)
RECOVERY: the workflow execution instance will not process new orders, but only continue processing workflow order data instances that need error recovery (corresponds to OMQ::WM_Recovery)

Output similar to the following should appear:

started with ID <id>

No error messages should appear. If an error message appears, see the following section for causes.

Note: If there is a significant number of data for the workflow, the Qorus server will continue to perform event queue population in background after this command has returned. Any DB errors encountered by background threads will be reported in log files and will not be visible on the command line.

Common Errors

Error: Unknown Workflow

Error Message:

ERROR: NO-SUCH-WORKFLOW: <name>/<version>

Explanation:: Qorus could not find any definition for the workflow name and version given.

Possible Cause	Action to Take
Workflow name and/or version is incorrect	Check the name and version and try again
The workflow has not yet been loaded	Load the workflow with the oload program

Error: System is Shutting Down

Error Message:

ERROR: cannot start new workflows because the system is shutting down

Explanation:: The shutdown command has been received and system shutdown is in progress.

Possible Cause	Action to Take
System is shutting down	After the system shuts down, restart it and then start the workflow.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Stop a Workflow Execution Instance By ID

To retrieve a list of running workflow execution instances and their IDs, use the "ostatus –w" command (see ostatus: Show System, Workflow, and Service Status).

To stop a workflow execution instance, enter the following at the command line:

unixprompt% ostop <id>

Output similar to the following should appear:

workflow with execution ID <id> is being stopped

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Workflow ID

Error Message:

ERROR there is no workflow with execution ID <id>

Explanation:: The ID does not correspond to a running workflow execution instance.

Possible Cause	Action to Take
The ID is invalid.	Check the list of running workflow execution instances and their IDs with `"ostatus –w"` and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Stop Workflow Execution Instances by Name

To stop workflow execution instances by name, the omq.system.stop-workflow() command must be sent to the server with the workflow name and an optional version as parameters. The ostop command provides a user-friendly command-line interface to this function.

To stop a workflow execution instance, enter the following at the command line:

unixprompt% ostop <name> [version]

Output similar to the following should appear:

<number> instances of <name>/[<version>,*] <is|are> being stopped

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Workflow

Error Message:

ERROR no instances of workflow <name>/<ver> are running

Explanation:: Qorus is not currently running any instances of the workflow name and version given.

Possible Cause	Action to Take
Workflow name and/or version is incorrect	Check the name and version and try again. To get a list of running workflow execution instances (with names, versions, ids, etc), execute `"ostatus –w"`

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Stop All Workflow Execution Instances

To stop all running workflow execution instances, call the omq.system.stop-all-workflows() API method using the ocmd program as follows:

unixprompt% ocmd stop-all-workflows

Output similar to the following should appear:

<num> workflow instances have been stopped

The command will not return until all workflow execution instances have been stopped. No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

View Workflow Execution Instance Options

To view options on all workflow execution instances, the omq.system.get-workflow-info() command must be sent to the API server. Execute the following command-line to send this command to the server:

unixprompt% ostatus -wv

Output similar to the following should appear:

Qorus 3.0.4.p7 psft-int-av2s329t-1 sessionid 340
workflows:
 W   23 RETIRE/1.0                NORMAL               42/ 6 itera... 
        + option: provident-no-messages = 1
 W   24 TRANSFER-USIM/1.0         NORMAL                0/ 9 itera...
        + option: provident-no-message = 1
        + option: provident-no-messages = 1

Information like the above will appear for each running workflow execution instance. No error messages should appear. If an error message appears, see the following section for causes.

Note: See Command-Line Programs for more information on system programs such as ostatus: Show System, Workflow, and Service Status.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Set Workflow Execution Instance Options

To set workflow execution instance options, the omq.system.set-workflow-option() command must be sent to the HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-workflow-option <id> <option>=<value>

Output similar to the following should appear:

options set on workflow with execution ID <id>

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Workflow Option

Error Message:

ERROR: WORKFLOW-OPTION-ERROR: list: ("invalid option '<option>'")

Explanation:: The option is not supported by this workflow.

Possible Cause	Action to Take
Option name is incorrect	Check the option name again and try the command again with the correct name.

Error: Invalid Workflow Execution Instance ID

Error Message:

ERROR: INVALID-WORKFLOW-ID: there is no workflow with execution ID 11

Explanation:: The workflow execution instance ID given does not correspond to a running workflow execution instance.

Possible Cause	Action to Take
Instance ID is incorrect	Check the execution instance ID again and try the command again with the correct ID number.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Queue Workflow Order Data Instance for Immediate Retry

To queue a workflow order data instance for immediate retry, the omq.system.retry-workflow-instance() API method must be called by sending an appropriately formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd retry-workflow-instance <id>

Output similar to the following should appear:

hash: (5 members)
  steps_updated : 0
  segments_updated : 1
  workflow_updated : True
  workflow_status : "RETRY"
  cached : False

No error messages should appear. If an error message appears, see the following section for causes.

Note: For more information on Qorus programs like ocmd, see Command-Line Programs; see System Options for more information on system options, see Network System API for more information on Qorus API methods

Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:

ERROR: INVALID-WORKFLOW-ORDER-DATA-INSTANCE: workflow_instanceid <x> does not exist

Explanation:: The workflow order data instance ID is not valid.

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:

ERROR: STATUS-ERROR: can't update status 'R' (RETRY)

Explanation:: The workflow order data instance ID has a status that cannot be updated to RETRY.

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.
The status is incorrect	Only workflow order data instances with status `"ERROR"` or `"ASYNC-WAITING"` can be set to `"RETRY"`. It is not possible to update workflow order data instances with other statuses to `"RETRY"`.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Skip Execution For a Step

Sometimes a step in a workflow order data instance cannot reach a "COMPLETE" status for reasons outside of the control of the workflow, but the rest of the workflow should be executed anyway on the order data instance. In these cases, either the omq.system.skip-step() or the omq.system.skip-step-without-retry() method must be called with the workflow instance ID, the step ID, and the step index (0 for non-array steps) as arguments. These methods will only update steps with an "ERROR", "RETRY", or "ASYNC-WAITING" status. Execute the following command-line to send the omq.system.skip-step() command to the server:

unixprompt% ocmd omq.system.skip-step <workflow_instanceid> <stepid> [<index>]

Output similar to the following should appear:

OK

No error messages should appear. If an error message appears, see the following section for causes.

Note: For more information on Qorus programs like ocmd, see Command-Line Programs; see Network System API for more information on Qorus API methods

Common Errors

Error: Cannot Update Subworkflow Step

Error Message:

ERROR: PARAMETER-ERROR: cannot call skipStep() on a subworkflow step

Explanation:: The step ID refers to a subworkflow step and subworkflow steps cannot be skipped at the top level; the child workflow must be corrected.

Possible Cause	Action to Take
The step ID refers to a subworkflow step	Correct the child workflow instead.

Error: Invalid Step ID

Error Message:

ERROR: SKIP-STEP-ERROR: stepid <id>/<id> has not been executed in workflow_instance <id>

Explanation:: The step ID and index combination could not be found in the STEP_INSTANCE table with this workflow_instanceid.

Possible Cause	Action to Take
One of the IDs is incorrect	Correct the ID and try the command again.

Error: Step Status Error

Error Message:

ERROR: STEP-STATUS-ERROR: can’t update steps with status <status>

Explanation:: The step does not have a status that allows it to be skipped.

Possible Cause	Action to Take
Step is `"IN-PROGRESS"`	Wait until the step has finished executing and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Set a Workflow Order Data Instance’s Status to ERROR

To set workflow order data instance’s status to "ERROR", the omq.system.set-workflow-instance-error() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-workflow-instance-error <id>

Output similar to the following should appear:

hash: (4 members)
  steps_updated : 1
  segments_updated : 1
  workflow_status : "ERROR"
  old_status : "RETRY"

No error messages should appear. If an error message appears, see the following section for causes.

Note: For more information on Qorus programs like ocmd, see Command-Line Programs; see Network System API for more information on Qorus API methods

Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:

ERROR: WORKFLOW-ERROR: workflow_instance_id <id> does not exist

Explanation:: The workflow order data instance ID is not valid.

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:

ERROR: WORKFLOW-STATUS-ERROR: <status>

Explanation:: The workflow order data instance ID has a status that cannot be updated to "ERROR"

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.
The status is incorrect	Only workflow order data instances with statuses: `"RETRY"`, `"CANCELED"`, `"ASYNC-WAITING"` can be set to `"ERROR"`. It is not possible to update workflow order data instances with other statuses to `"ERROR"`.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Set a Workflow Order Data Instance’s Status to CANCELED

To set workflow order data instance’s status to "CANCELED", the omq.system.cancel-workflow-instance() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd omq.system.cancel-workflow-instance <id>

Output similar to the following should appear:

hash: (1 member)
  workflow_status : "CANCELED"

No error messages should appear. If an error message appears, see the following section for causes.

Note: For more information on Qorus programs like ocmd, see Command-Line Programs; see Network System API for more information on Qorus API methods

Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:

ERROR: INVALID-WORKFLOW-ORDER-DATA-INSTANCE: workflow_instanceid <x> does not exist

Explanation:: The workflow order data instance ID is not valid.

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:

ERROR: CANCEL-WORKFLOW-STATUS-ERROR: <status>

Explanation:: The workflow order data instance ID has a status that cannot be updated to "CANCELED".

Possible Cause	Action to Take
The ID is incorrect	Correct the ID and try the command again.
The status is incorrect	Only workflow order data instances with statuses: `"RETRY"`, `"ERROR"`, `"ASYNC-WAITING"`, and `"WAITING"` can be set to `"CANCELED"`. It is not possible to update workflow order data instances with other statuses to `"CANCELED"`.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Perform a Live Upgrade of a Workflow

A live upgrade of a workflow entails updating a workflow definition for a workflow that has running execution instances.

To upgrade a workflow, the following steps must be taken:

Load the new workflow version in the database
Reset the cached workflow configuration

Workflows should be delivered with their own installation scripts and instructions; in this case follow the instructions delivered with your workflow’s installation script to load the new configuration into the Qorus system schema and reset the cached workflow configuration.

In case the workflow’s configuration should be updated by hand, follow the following steps.

For instance, if EXAMPLE-WORKFLOW 1.1 is being updated and has a load script of example-workflow-1.1.qrf, then the following command will load the new version of the workflow into the database:

unixprompt% oload @example-workflow-1.1.qrf

The exact output will depend on the objects being updated in the release file, however here is an example:

installing Qorus user code from: example-workflow-1.1.qrf
installing release files: done
executing release files
creating functions from user/EXAMPLE-WORKFLOW/example-v1.1p1.qfd
done executing release files
installation complete!

Any workflows running will be load the new configuration of the workflow from the database and use it whenever the omq.system.reset-workflow() method is called, without having to shut down the running workflow execution instances and restart them. In this way workflow logic can be upgraded without causing an interruption of service.

Note: A workflow can only recover workflow order data instances that have the same workflow ID (name and version), for example, you cannot use EXAMPLE-WORKFLOW 1.1 to recover instances of EXAMPLE-WORKFLOW 1.0. If a bug is found in EXAMPLE-WORKFLOW 1.0 and a new version of the workflow must be released and instances of EXAMPLE-WORKFLOW 1.0 should be recovered by the new version, then EXAMPLE-WORKFLOW 1.0 should be loaded with a patched redefinition instead of creating EXAMPLE-WORKFLOW 1.1.

Common Errors

Error: Workflow is not Cached

Error Message:

ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<id> is not currently cached

Explanation:: The workflow configuration cannot be reset because it is not currently cached.

Possible Cause	Action to Take
Workflow is not running	Normally installation scripts will specify that any updated workflows have their configurations reset, however if the workflow is not currently running, then it cannot be reset. In this case the error message can be ignored, because the workflow will run with the new configuration the next time it is run.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Check Workflow Order Overall Status

To check the overall status of processing of a workflow’s order data instances, there are several Qorus API methods that can be used, such as the omq.system.service.info.getWorkflowOverview() and the omq.system.service.info.getWorkflowOverviewFromName() methods. The oview program provides a user-friendly command-line interface to these methods (among others).

For example, to see the overall status of EXAMPLE-WORKFLOW 1.1 in the last 24 hours:

unixprompt% oview EXAMPLE-WORKFLOW:1.1

Assuming the workflow has been processing data in the last 24 hours, the output should look something like the following (the output has been truncated for formatting purposes):

                                          READY INCOMPLETE ASYNC-WAIT...
EXAMPLE-WORKFLOW        1.1                 20          2          3...

If an error message appears, see the following section for causes.

Note: The oview program can be used to view overall status from one, many, or all workflows, to view detailed workflow/order information, and supports flexible time periods for aggregate reporting, depending on the options given on the command-line.

Common Errors

Error: Unknown Workflow>

Error Message:

ERROR: UNKNOWN-WORKFLOW: workflow <name>: does not exist

Explanation:: The named workflow does not exist.

Possible Cause	Action to Take
The workflow name is incorrect	Check the workflow name and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Check Workflow Order Data Instance Status

To get detailed information on a single workflow order data instance’s status, there are several Qorus API methods that can be used, such as the omq.system.service.info.getWorkflowStatus() and the omq.system.service.info.getOrderInfo() methods. The oview program provides a user-friendly command-line interface to these methods (among others).

For example, to see the detailed status of workflow order data instance ID 419649, with step and segment details:

unixprompt% oview w419649 -ssg

Assuming the workflow has been processing data in the last 24 hours, the output should look something like the following (the output has been truncated for formatting purposes):

w:419619: PORTOUT_REQPORTING_OGW 1.0(1044)      (errors:  0) COMPLETE
    + SEGMENT  0: 005/005 steps executed                     COMPLETE
      + STEP: 716        createTransactionIdFunction 1.0     COMPLETE
      + STEP: 899        storePortingDateRequestFunction 1.0 COMPLETE
      + STEP: 900        checkMNPStatusFunction 1.0          COMPLETE
      + STEP: 996        checkPortingPinAndMSISDN 1.0        COMPLETE
      + STEP: 901     S  checkMSISDNBarredEAIFunction 1.0    COMPLETE
    + SEGMENT  1: 007/007 steps executed                     COMPLETE
      + STEP: 901     S  checkMSISDNBarredEAIFunction 1.0    COMPLETE
      + STEP: 902        checkLocalCalendarFunction 1.0      COMPLETE
      + STEP: 903        setMainMsisdnAndServicesForMsisdnsI COMPLETE
      + STEP: 904        checkIfVoiceAndVoiceBoxIncludedFunc COMPLETE
      + STEP: 905        copyReservationIDFromMsisdnNuevFunc COMPLETE
      + STEP: 907        updatePortingCalendarFunction 1.0   COMPLETE

If an error message appears, see the following section for causes.

Note: The oview program can be used to view overall status from one, many, or all workflows, to view detailed workflow/order information, and supports flexible time periods for aggregate reporting, depending on the options given on the command-line.

Common Errors

Error: No Such Workflow Order Data Instance

Error Message:

workflow_instanceid <id>: no results

Explanation: The workflow order data instance ID does not exist.

Possible Cause	Action to Take
The ID is incorrect	Check the ID and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Reset a Workflow’s Configuration

Workflow configurations may need to be updated, for example, if a new configuration has been loaded into the database, or if a resource definition for a resource acquired during the workflow’s one-time-initialization is updated (such as a datasource or TIBCO adapter).

To reset a workflow’s cached configuration, the omq.system.reset-workflow() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow’s name and optionally the version as parameters as follows (note that if the version argument is omitted, all versions of the named workflow will be reset):

unixprompt% ocmd reset-workflow <name> [version]

Output similar to the following should appear:

workflow <name>/<version> has been deleted from the cache and will be reloaded on next reference

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Workflow Option

Error Message:

ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<version> is not currently cached

Explanation:: The workflow’s cached configuration cannot be reset because it is not cached.

Possible Cause	Action to Take
Workflow name or version is incorrect	Check the input and try the command again with the correct parameters.
Workflow is not cached	Take no action

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.

Order Instance Notes

Each workflow instance (order instance) can contain unlimited notes. Operators can store additional info or reference to tracking systems etc.

omq.system.order-notes
omq.system.set-order-note workflowinstanceid note

Notes are displayed in user interface out of the box.