Qorus Integration Engine®  5.1.31_git
Workflow API Reference

Introduction to the Qorus Workflow API

See also

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 for the Qore proggramming language.

Workflow API

The workflow APIs are documented here:

The base classes for steps are the following:

This means that step methods can call the static methods defined in the base class directly.

For library classes and other workflow code, calls must be prefixed with the class name.

Qore Workflow Program Container

Each workflow has a single Qore Program logic container containing all its code for the workflow, 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 logic containers are created with the following sandbox flags:

Directive Constant Description
%allow-weak-references Qore::PO_ALLOW_WEAK_REFERENCES the := operator may be used
%no-global-vars Qore::PO_NO_GLOBAL_VARS Global variables may not be defined
%no-process-control Qore::PO_NO_PROCESS_CONTROL Functionality that affects the entire process is unavailable
%no-thread-control Qore::PO_NO_THREAD_CONTROL Thread management functionality is unavailable
%no-top-level Qore::PO_NO_TOP_LEVEL_STATEMENTS No code is allowed in the top-level statement (outside a function or class)
%require-our Qore::PO_REQUIRE_OUR All variables must be declared before use

Additionally, each workflow's Program container is set up with the following imported objects:

In addition to the above, all public constants in the OMQ namespace are available.

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 sandbox restrictions apply to Qore code; code in other languages such as Java is not subject to these restrictions.

Furthermore, the following parse defines are defined:

Define Availability Description
Qorus W, S, J Identifies code in Qorus
QorusHasAlerts W, S, J Marks the availability of the alert API (Qorus 3.0+)
QorusHasTableCache W, S, J Marks the availability of the table cache API (Qorus 3.1+)
QorusHasUserConnections W, S, J Marks the availability of the connection API (Qorus 3.0+)
QorusServer W, S, J Identifies code used in Qorus server interfaces
QorusWorkflow W Identifies code used in a workflow Program container
Note
All defines set in qorus.defines (common to workflows, services, and jobs) are also set in Workflow Program containers

Workflow APIs

The following APIs are imported into workflow program logic containers:

API Method Domain Availability Description
UserApi::auditCheckEventString() Audit W, S, J checks if the given audit event (given as a string) is enabled
UserApi::auditCheckEvent() Audit W, S, J checks if the given audit event (given as an integer code) is enabled
UserApi::auditGetMask() Audit W, S, J returns the audit event mask
UserApi::auditUserEvent() Audit W, S, J creates a user audit event (with audit event code OMQ::AE_USER_EVENT) against the workflow, service, or job instance
UserApi::callNetworkApi() Utility W, S, J calls a system RPC API with system permissions
UserApi::callNetworkApiArgs() Utility W, S, J calls a system RPC API with system permissions with an explicit argument list argument
UserApi::callNetworkApiArgsWithAuthentication() Utility W, S, J calls a system RPC API with authentication information (username and password)
UserApi::callRestApi() Utility W, S, J calls a system REST API with system permissions
UserApi::callRestApiWithAuthentication() Utility W, S, J calls a system REST API with authentication information (username and password)
UserApi::clearSqlTableCache() SQL Cache W, S, J clears a cached table from the SQL cache
UserApi::createOrder() Utility W, S, J creates a workflow order data instance in the database and returns the workflow_instanceid of the order created
UserApi::createRemoteOrder() Utility W, S, J creates a workflow order data instance in a remote Qorus instance and returns the workflow_instanceid of the order created
UserApi::deserializeQorusData() Utility W, S, J deserializes strings to Qore data structures
UserApi::execSynchronousWorkflow() Utility W, S, J executes a workflow order synchronously and returns the result of execution
UserApi::executeFsm() Utility W, S, J executes a finite state machine registered with the interface and returns the result
UserApi::flushSlaEvents() SLA W, S, J flushes all pending SLA events to the DB
UserApi::getActiveJobs() System Info W, S, J returns information about active jobs
WorkflowApi::getConfigItemHash() n/a W retrieves a hash of all step configuration items
WorkflowApi::getConfigItemValue() n/a W retrieves the value of a step configuration item
UserApi::getDatasourceDedicated() Connections W, S, J returns a dedicated Qore::SQL::Datasource object
UserApi::getDatasourcePool() Connections W, S, J returns a shared Qore::SQL::DatasourcePool object
UserApi::getGlobalConfigItemValue() Qorus System Information API W, S, J returns the value of the given configuration item on global level
WorkflowApi::getOption() Options W, S, J returns the value of one or more system or interface options
UserApi::getQorusOptions() Options W, S, J returns the value of system options
UserApi::getQorusOptionsArgs() Options W, S, J returns the value of system options
UserApi::getQorusOptionInfo() Options W, S, J returns information about system options
UserApi::getQorusOptionInfoArgs() Options W, S, J returns information about system options
UserApi::getRemoteRestConnection() Connections W, S, J returns a QorusSystemRestHelper to a remote Qorus instance
UserApi::getRemoteRpcConnection() Connections W, S, J returns a QorusSystemAPIHelper to a remote Qorus instance
UserApi::getRunningWorkflowInfo() System Info W, S, J returns information about a running workflow execution instance
UserApi::getRunningWorkflowList() System Info W, S, J returns information about running workflow execution instances
UserApi::getServiceInfo() System Info W, S, J returns information about a service
UserApi::getSessionId() System Info W, S, J returns the current application session ID
UserApi::getSqlTable() SQL Cache W, S, J retrieves an AbstractTable object from the SQL cache for DML operations
UserApi::getSqlCacheInfo() SQL Cache W, S, J returns information about the SQL cache
UserApi::getSystemInfo() System Info W, S, J returns information about the system
UserApi::getSystemServiceInfo() System Info W, S, J returns information about a system service
UserApi::getUserConnection() Connections W, S, J returns the given user connection object
UserApi::getUserServiceInfo() System Info W, S, J returns information about a user service
UserApi::getValueMap() Value Maps W, S, J retrieves a value mapping from a value map
UserApi::getValueMaps() Value Maps W, S, J retrieves a list of all known value sets
UserApi::logInfo() logging W, S, J outputs a log message in the workflow's log file
UserApi::getNextSequenceValue() Utility W, S, J returns the next value from the given datasource and database sequence
UserApi::sleep() Utility W, S, J safely pause execution for a defined period of time
UserApi::usleep() Utility W, S, J safely pause execution for a defined period of time
UserApi::postSlaEventError() SLA W, S, J posts an unsuccessful event for SLA and performance tracking
UserApi::postSlaEventSuccess() SLA W, S, J posts a successful event for SLA and performance tracking
UserApi::postSyncEvent() Utility W, S, J posts a workflow synchronization event given the event type name and event key
UserApi::postUserEvent() Utility W, S, J posts an application event of class OMQ::QE_CLASS_USER
UserApi::propGet() System Props W, S, J returns the value of the given system property key in the given domain or NOTHING if the system property does not exist
UserApi::propUpdate() System Props W, S, J changes (inserts, updates, or deletes) the value of one or more system properties
UserApi::qorusGetLocalUrl() System Info W, S, J returns a URL for the current system
UserApi::raiseTransientAlert() Alerts W, S, J raises a transient alert
UserApi::registerFsmAsObserver() Utility W, S, J registers a finite state machine as an event observer
UserApi::restartTransaction() Utility W, S, J enables recovery from restartable DB communication errors
UserApi::runtimeProperties() System Info W, S, J returns information about runtime system defines defined
UserApi::serializeQorusData() Utility W, S, J serializes Qore data structures to strings
WorkflowApi::setOption() Options W, S, J sets option values on a workflow, service, or job
WorkflowApi::addOrderNote() WF Misc W adds a note to a workflow order
QorusEventStepBase::bindEvent() WF Event W binds a workflow synchronization event to the current binds a workflow synchronization event to the current workflow synchronization event step
QorusEventStepBase::bindEventUnposted() WF Event W binds an unposted workflow synchronization event to the current workflow synchronization event step
QorusSubworkflowStepBase::bindSubworkflow() WF Sub W binds a subworkflow to the current subworkflow step
WorkflowApi::deleteDynamicDataKey() WF Data W deletes a key in Workflow Dynamic Order Data
WorkflowApi::deleteInstanceDataKey() WF Data W deletes a key in Workflow Execution Instance Data
WorkflowApi::deleteSensitiveData() WF Data W deletes the sensitive data hash for the given sensitive data key and value
WorkflowApi::deleteSensitiveDataKey() WF Data W deletes one or more keys from the workflow order data instance’s sensitive data hash for the given sensitive data key and value
WorkflowApi::deleteTempDataKey() WF Data W deletes a key in Workflow Temporary Order Data
WorkflowApi::generateUniqueKey() WF Misc W returns a unique key that can be used for an asynchronous step event key
WorkflowApi::getDynamicData() WF Data W retrieves information from Workflow Dynamic Order Data
WorkflowApi::getErrorInfo() WF Misc W returns information about the given workflow error
WorkflowApi::getInstanceData() WF Data W retrieves information from Workflow Execution Instance Data
WorkflowApi::getOrderKeys() WF Misc W returns information about order keys associated with the current workflow order
WorkflowApi::getOrderNotes() WF Misc W retrieves notes saved against the workflow order
WorkflowApi::parentWfiid() WF Misc W returns the current workflow order's parent workflow_instanceid, if any
WorkflowApi::getSensitiveData() WF Data W retrieves the sensitive data hash for the given sensitive data key and value
WorkflowApi::getSensitiveDataFromAlias() WF Data W retrieves the sensitive data hash for the given sensitive data alias
WorkflowApi::getSensitiveDataKeyValues() WF Data W retrieves a hash of sensitive data keys and values saved against the order
WorkflowApi::getStaticData() WF Data W retrieves information from Workflow Static Order Data
WorkflowApi::getStepInfo() WF Misc W returns information about the current step
WorkflowApi::getStepStatus() WF Misc W returns information about the status of the given step
WorkflowApi::getTempData() WF Data W retrieves information from Workflow Temporary Order Data
WorkflowApi::getWorkflowInstanceData() WF Data W retrieves information from the running workflow execution instance itself
WorkflowApi::getWorkflowMetadata() WF Misc W returns workflow metadata for the current workflow
WorkflowApi::parentWfiid() WF Misc W returns the order's parent workflow_instanceid, if any, otherwise returns NOTHING
WorkflowApi::rescheduleOrder() WF Attach W changes the earliest possible processing date for the current workflow order instance in the attach logic
WorkflowApi::reprioritizeOrder() WF Misc W set the priority value of a workflow order instance
WorkflowApi::setBlocked() WF Attach W sets the current workflow order instance to status OMQ::StatBlocked in the attach logic
WorkflowApi::setRetryDelay() WF Errors W sets the retry delay explicitly after raising an error against the workflow order instance with wf_serror()
WorkflowApi::setCustomStatus() WF Misc W sets a custom status value for the current workflow order data instance
WorkflowApi::setOrderKeys() WF Misc W sets order keys on the current workflow order instance
WorkflowApi::stepError() WF Errors W raises an error against the workflow order data without affecting the flow of processing
QorusAsyncStepBase::skipAsyncStep() WF Async W skips setting an asynchronous key for an asynchronous step
QorusEventStepBase::skipEvent() WF Event W skips binding a workflow synchronization event to the current workflow synchronization event step
QorusSubworkflowStepBase::skipSubworkflow() WF Sub W skips the subworkflow bind in a subworkflow step
WorkflowApi::stepExecuted() WF Misc W verifies if a step has been executed on the current workflow order instance and has status COMPLETE
QorusAsyncStepBase::submitAsyncKey() WF Async W submits an async key for an asynchronous step
WorkflowApi::() WF Errors W raises a warning against the workflow order data
WorkflowApi::updateDynamicData() WF Data W performs an update in Workflow Dynamic Order Data
WorkflowApi::updateInstanceData() WF Data W performs an update in Workflow Execution Instance Data
WorkflowApi::updateSensitiveData() WF Data W performs an update in Sensitive Data
WorkflowApi::updateSensitiveDataFromAlias() WF Data W performs an update in Sensitive Data from a sensitive data alias
WorkflowApi::updateTempData() WF Data W performs an update in Workflow Temporary Order Data
WorkflowApi::getWfiid() WF Misc W returns the current order's workflow_instanceid

Workflow API Classes

The following classes are imported into workflow program logic containers:

Class Availability Description
AbstractFsRemoteReceive W, S, J provides an API for streaming data from a remote filesystem through a remote Qorus instance
AbstractParallelStream W, S, J provides an abstract base class for streaming data to or from a remote database through a remote Qorus instance and also provides static helper methods
DbRemote W, S, J provides an API wrapper for all system.sqlutil service methods
DbRemoteReceive W, S, J provides an API for streaming data from a remote database through a remote Qorus instance
DbRemoteSend W, S, J provides an API for streaming data to a remote database through a remote Qorus instance
DynamicDataHelper W provides an API for managing dynamic data atomically in workflows
FsRemote W, S, J provides an API wrapper for all system.fs service methods
FsRemoteSend W, S, J provides an API for streaming data to a remote filesystem through a remote Qorus instance
QorusInboundTableMapper W, S, J provides an API for mapping data to a DB table
QorusInboundTableMapperIterator W, S, J provides an iterator-based API for mapping data to a DB table
QorusRawSqlStatementOutboundMapper W, S, J provides an API for mapping from SQL statement using direct SQL statements passed in
QorusRemoteServiceHelper W, S, J provides an API for calling service methods in remote Qorus instances
QorusSqlStatementOutboundMapper W, S, J provides an API for mapping from SQL statement using SqlUtil
QorusSystemAPIHelper W, S, J provides an API for calling RPC API methods in remote Qorus instances
OMQ::QorusSystemRestHelper W, S, J provides an API for using the REST API in remote Qorus instances
SensitiveDataHelper W provides an API for managing sensitive data atomically in workflows
TempDataHelper W provides an API for managing temp data atomically in workflows
UserApi W, S, J the primary shared Qorus API class
WorkflowApi W the primary workflow API class

Workflow API Qore Modules

The following modules are imported by default into Qore workflow program logic containers:

Name Availability Description
json W, S, J provides APIs for JSON data serialization and deserialization support
Mime W, S, J provides MIME definitions and functionality
Mapper W, S, J provides a data-mapping API
SoapClient W, S, J provides a SOAP client API
SqlUtil W, S, J provides high-level APIs for programmatic DML (SQL data manipulation), DDL (creating, querying, manipulating database definitions), and DBA operations
TableMapper W, S, J provides high-level APIs for mapping data to and from database tables
Util W, S, J provides utility APIs
uuid W, S, J provides an API for generating UUIDs
xml W, S, J provides APIs for parsing, validating, and generating XML documents
yaml W, S, J provides APIs for Qore's YAML-based data serialization and deserialization support
Note
other modules can be imported using the %requires directive, and it's always safe to %require a module that's already imported into the current Program container

Workflow API Overview

This section lists all of the API methods specific to workflows; the main workflow API classes are:

Note
  • Workflow-specific API functions have been superceded by the API classes listed above; the old workflow api functions can be found in the OMQ::UserApi::Workflow namespace and are prefixed by "wf_" and are deprecated.
  • Qorus class-based steps should inherit a specific class depending on the step type; see Step Source Class Definitions for more information
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.

Logging APIs:

Workflow Miscellaneous API

Miscellaneous workflow API methods:

API Method Desc
WorkflowApi::addOrderNote() adds a note to a workflow order
WorkflowApi::generateUniqueKey() returns a unique key that can be used for an asynchronous step event key
WorkflowApi::getErrorInfo() returns information about the given workflow error
WorkflowApi::getOrderKeys() returns information about order keys associated with the current workflow order
WorkflowApi::getOrderNotes() retrieves notes saved against the workflow order
WorkflowApi::getStepInfo() returns information about the current step
WorkflowApi::getStepStatus() returns information about the status of the given step
WorkflowApi::getWfiid() returns the current order's workflow_instanceid
WorkflowApi::getWorkflowMetadata() returns workflow metadata for the current workflow
WorkflowApi::parentWfiid() returns the order's parent workflow_instanceid, if any, otherwise returns NOTHING
WorkflowApi::reprioritizeOrder() set the priority value of a workflow order instance
WorkflowApi::setCustomStatus() sets a custom status value for the current workflow order data instance
WorkflowApi::setOrderKeys() sets order keys on the current workflow order instance
UserApi::sleep() safely pause execution for a defined period of time
WorkflowApi::stepExecuted() verifies if a step has been executed on the current workflow order instance and has status COMPLETE
UserApi::usleep() safely pause execution for a defined period of time

Workflow Data API

API calls related to workflow data (see Workflow Data):

API Method Desc
WorkflowApi::deleteDynamicDataKey() deletes a key in Workflow Dynamic Order Data
WorkflowApi::deleteDynamicDataKey() deletes a key in Workflow Dynamic Order Data
WorkflowApi::deleteInstanceDataKey() deletes a key in Workflow Execution Instance Data
WorkflowApi::deleteSensitiveData() deletes the sensitive data hash for the given sensitive data key and value
WorkflowApi::deleteSensitiveDataKey() deletes one or more keys from the workflow order data instance’s sensitive data hash for the given sensitive data key and value
WorkflowApi::deleteTempDataKey() deletes a key in Workflow Temporary Order Data
WorkflowApi::getDynamicData() retrieves information from Workflow Dynamic Order Data
WorkflowApi::getInstanceData() retrieves information from Workflow Execution Instance Data
WorkflowApi::getSensitiveData() retrieves the sensitive data hash for the given sensitive data key and value
WorkflowApi::getSensitiveDataFromAlias() retrieves the sensitive data hash for the given sensitive data alias
WorkflowApi::getSensitiveDataKeyValues() retrieves a hash of sensitive data keys and values saved against the order
WorkflowApi::getStaticData() retrieves information from Workflow Static Order Data
WorkflowApi::getTempData() retrieves information from Workflow Temporary Order Data
WorkflowApi::getWorkflowInstanceData() retrieves information from the running workflow execution instance itself
WorkflowApi::updateDynamicData() performs an update in Workflow Dynamic Order Data
WorkflowApi::updateInstanceData() performs an update in Workflow Execution Instance Data
WorkflowApi::updateSensitiveData() performs an update in Sensitive Data
WorkflowApi::updateSensitiveDataFromAlias() performs an update in Sensitive Data from a sensitive data alias
WorkflowApi::updateTempData() performs an update in Workflow Temporary Order Data

Workflow Error-Handling API

APIs related to workflow error handling:

API Method Desc
WorkflowApi::stepError() raises an error against the workflow order data without affecting the flow of processing
WorkflowApi::setRetryDelay() sets the retry delay explicitly after raising an error against the workflow order instance with WorkflowApi::stepError()
WorkflowApi::stepWarning() raises a warning against the workflow order data

Workflow Async API

API calls that can only be called from asynchronous steps:

API Method Desc
QorusAsyncStepBase::skipAsyncStep() skips setting an asynchronous key for an asynchronous step
QorusAsyncStepBase::submitAsyncKey() submits an async key for an asynchronous step
Note
Class-based asynchronous steps should inherit one of the following classes where the above methods are implemented:

Workflow Subworkflow API

API calls that can only be called from subworkflow steps:

API Method Desc
QorusSubworkflowStepBase::bindSubworkflow() binds a subworkflow to the current subworkflow step
QorusSubworkflowStepBase::skipSubworkflow() skips the subworkflow bind in a subworkflow step
Note
Class-based subworkflow steps should inherit one of the following classes where the above methods are implemented:

Workflow Event Synchronization API

API calls that can only be called from workflow synchronization event steps:

API Method Desc
QorusEventStepBase::bindEvent() binds a workflow synchronization event to the current workflow synchronization event step
QorusEventStepBase::bindEventUnposted() binds an unposted workflow synchronization event to the current workflow synchronization event step
QorusEventStepBase::skipEvent() skips binding a workflow synchronization event to the current workflow synchronization event step
Note
Class-based event steps should inherit one of the following classes where the above methods are implemented:

Workflow Attach API

API calls that can only be called from the attach logic:

API Method Desc
WorkflowApi::setBlocked() sets the current workflow order instance to status OMQ::StatBlocked in the attach logic
WorkflowApi::rescheduleOrder() changes the earliest possible processing date for the current workflow order instance in the attach logic