Qorus Integration Engine  3.0.4.p7
Workflow API Reference

Introduction to the Qorus Workflow API

This section describes additional classes, constants, and functions that are imported into workflow Program objects by the Qorus system itself that make up the Qorus Workflow API.

Workflow Program Container

Each workflow has a single Qore Program object containing all its code for the step, array, validation, async end functions, as well as any objects imported into the Program object (classes, constants, and functions listed as attributes of the workflow when the workflow is defined).

Workflow Program objects are restricted from using elements of the Qore Language related to process and thread control; the use of these functions is either dangerous or could violate the integrity of the Qorus server process and therefore is restricted.

To enforce these restrictions, workflow Program objects are created with the following parse restrictions:

Please see the above links for more information on the features made unavailable when these parse options are set.

Please note that despite these restrictions, workflow program objects have most of the Qore language API and class library available for use.

Furthermore, the following parse defines are defined:

  • "Qorus" (common to workflows, services, and jobs)
  • "QorusServer" (common to workflows, services, and jobs)
  • "QorusHasUserConnections" (common to workflows, services, and jobs)
  • "QorusHasAlerts" (common to workflows, services, and jobs)
  • "QorusWorkflow" (workflow-specific)
  • all defines set in defines (common to workflows, services, and jobs)

Workflow API Overview

This section will list all of the functions specific to processing workflows. Note that there is a separate section (below) describing how to work with workflow data in detail.

See also
Qorus Common Server API for APIs and API concepts common to all Qorus server code (workflows, services, and jobs).
Qorus Common API for a definition of API definitions common to all Qorus user code (workflows, services, and jobs) as well as the client library.

Note that workflow-specific API functions are found in the OMQ::UserApi::Workflow namespace and are prefixed by "wf_" for consistency's sake and ease of identification.

Logging function (common API function):

Miscellaneous workflow API functions:

Functions related to workflow data (see Workflow Data):

Functions related to error handling:

Functions that can only be called from asynchronous steps:

Functions that can only be called from subworkflow steps:

Functions that can only be called from workflow synchronization event steps:

Functions that can only be called from the attach function:

Function to change order priority:

Old backwards-compatible workflow API functions (will be maintained indefinitely for backwards compatibility):

Workflow Data

Because a running workflow execution instance can be working on several different orders at once in different threads, accessing workflow data is performed through API calls in order to guarantee that the workflow's program code accesses only the correct data for the current order being processed at all times.

Accessing and processing data is done using the Qorus API as outlined in this section; these APIs set up the data context for each thread so that the correct data is accessed.

Note
Global variables are not allowed in workflow program objects; for a functional equivalent to global variables, see Workflow Execution Instance Data

Workflow Static Order Data

Static data represents the workflow order data being processed. Workflow static order data cannot be updated or deleted by the Qorus workflow API; it is read-only data representing the order data to be processed or fulfilled by the workflow.

functions:

The information returned by the above function corresponds to the deserialized contents of the field ORDER_INSTANCE.STATICDATA.

Workflow Dynamic Data

Dynamic data is associated with the workflow order data instance being processed, but it can be updated and is persistent. Any changes made to dynamic data will be committed to the database before the update function returns, therefore any changes will be available in the future, even in the case of errors and later recovery processing.

Dynamic data is appropriate for storing identifiers and references generated during order processing that are needed in subsequent steps, for example.

functions:

Workflow Temporary Data

Qorus maintains a hash of temporary data associated to the workflow order data instance being processed. This hash can be updated, but it is not persistent, therefore this hash is suitable for temporary data storage only.

This data is lost every time Qorus detaches (i.e. temporarily or permanently stops processing a workflow order data instance, for example, due to an ERROR status and purges the data from the workflow data cache) from a workflow order data instance.

Because temporary data is deleted every time Qorus detaches from a workflow order data instance, it can only be reliably set in the attach function.

functions:

Workflow Execution Instance Data

Workflow execution instance data is stored in a hash maintained by the system. This data is local to the running workflow execution instance pseudo-process and persists until the workflow execution instance terminates.

Any changes made to this data will persist within the running workflow execution instance (pseudo-process) independently of the workflow order data processed.

Because of this, workflow execution instance data is a substitute for global variables in a workflow program. Workflow programs are shared between all running workflow execution instances of that same type (sharing the same name and version and the same workflowid); global variables are not allowed because it is considered unsafe for workflow execution instances to share any common state. If your workflows do need to share some data between execution instances, implement a Qorus service to provide this functionality instead.

Typically workflow execution instance data will be set in the onetimeinit function (initializing resources for the workflow execution instance), and read by the rest of the workflow.

functions:

Workflow Information

Workflow Metadata

The following properties of the workflow metadata can be returned by the wf_get_workflow_metadata() function:

  • name: name of the workflow
  • version: version of the workflow
  • patch: The patch attribute of the workflow
  • workflowid: ID of the current workflow (metadata ID)
  • description: The description of the workflow
  • cached: The date and time the workflow metadata was read and cached from the database
  • errorfunction_instanceid: The function instance ID of the error function of the workflow
  • attach_func_instanceid: The function instance ID of the attach function for the workflow
  • detach_func_instanceid: The function instance ID of the detach function for the workflow
  • onetimeinit_func_instanceid: The function instance ID of the onetimeinit function for the workflow
  • errorhandler_func_instanceid: The function instance ID of the error handler function for the workflow
  • keylist: A list of valid order keys for the workflow
  • errors: The error hash as returned from the error function
  • options: A hash of valid workflow options, key = option, value = description

Running Workflow Execution Instance Properties

Properties of the current running workflow execution instance can be retrieved via the wf_get_workflow_instance_data() function.

The following keys are valid for this function:

  • dbstatus: the status of the workflow order in the database (for the current status, see the status key, see Workflow, Segment, and Step Status Descriptions for possible values); this will normally be OMQ::StatInProgress, unless called from the Detach Function (first available in Qorus 2.6.2)
  • external_order_instanceid: The external order instance ID saved against the order, if any
  • execid: the execution instance ID (workflow pseudo-process ID, first available in Qorus 2.6.0.3)
  • initstatus: the status of the workflow when it was cached (before it was updated to OMQ::StatInProgress, see Workflow, Segment, and Step Status Descriptions for possible values); note that synchronous workflow orders are created with status OMQ::StatInProgress, so initstatus should always be OMQ::StatInProgress for synchronous orders (first available in Qorus 2.6.2)
  • instancemode: The mode the workflow execution instance process is running in (OMQ::WM_Normal, OMQ::WM_Recovery, or OMQ::WM_Synchronous) OMQ::StatInProgress, unless called from the Detach Function
  • mode: The mode the current thread is running in (OMQ::WM_Normal or OMQ::WM_Recovery)
  • name: name of the workflow
  • parent_workflow_instanceid: The workflow order data instance ID of the parent workflow if the current workflow is a subworkflow, NOTHING if not
  • priority: The priority (0 - 999) of the workflow order data instance (first available in Qorus 2.6.0.3)
  • started: The date/time the workflow order data instance was created (first available in Qorus 2.6.0.3)
  • status: The current status of the workflow order data instance (see Workflow, Segment, and Step Status Descriptions for possible values); this will normally be OMQ::StatInProgress; first available in Qorus 2.6.2)
  • version: version of the workflow
  • workflowid: ID of the current workflow (metadata ID)
  • workflow_instanceid: The current workflow order data instance ID being processed