Qorus Integration Engine®  3.1.1.p9
Workflow API Reference

Introduction to the Qorus Workflow API

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.

See also
Designing and Implementing Workflows

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 logic container 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 logic containers are created with the following parse restrictions:

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

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:

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 defines (common to workflows, services, and jobs) are also set in Workflow Program containers

Workflow API Functions

The following functions are imported into workflow program logic containers (see also OMQ::UserApi::Workflow):

Name Domain Availability Description
audit_check_event_string() Audit W, S, J checks if the given audit event (given as a string) is enabled
audit_check_event() Audit W, S, J checks if the given audit event (given as an integer code) is enabled
audit_get_mask() Audit W, S, J returns the audit event mask
audit_user_event() Audit W, S, J creates a user audit event (with audit event code OMQ::AE_USER_EVENT) against the workflow, service, or job instance
call_network_api() Utility W, S, J calls a system RPC API with system permissions
call_network_api_args() Utility W, S, J calls a system RPC API with system permissions with an explicit argument list argument
call_network_api_args_with_authentication() Utility W, S, J calls a system RPC API with authentication information (username and password)
call_rest_api() Utility W, S, J calls a system REST API with system permissions
call_rest_api_with_authentication() Utility W, S, J calls a system REST API with authentication information (username and password)
clear_sql_table_cache() SQL Cache W, S, J clears a cached table from the SQL cache
create_order() Utility W, S, J creates a workflow order data instance in the database and returns the workflow_instanceid of the order created
create_remote_order() Utility W, S, J creates a workflow order data instance in a remote Qorus instance and returns the workflow_instanceid of the order created
deserialize_qorus_data() Utility W, S, J deserializes strings to Qore data structures
exec_synchronous_workflow() Utility W, S, J executes a workflow order synchronously and returns the result of execution
flush_sla_events() SLA W, S, J flushes all pending SLA events to the DB
get_active_jobs() System Info W, S, J returns information about active jobs
get_datasource_dedicated() Connections W, S, J returns a dedicated Qore::SQL::Datasource object
get_datasource_pool() Connections W, S, J returns a shared Qore::SQL::DatasourcePool object
get_datasource_shared() Connections W, S, J returns a shared Qore::SQL::Datasource object
get_option() Options W, S, J returns the value of one or more system or interface options
get_qorus_options() Options W, S, J returns the value of system options
get_qorus_options_args() Options W, S, J returns the value of system options
get_qorus_option_info() Options W, S, J returns information about system options
get_qorus_option_info_args() Options W, S, J returns information about system options
get_remote_rest_connection() Connections W, S, J returns a QorusSystemRestHelper to a remote Qorus instance
get_remote_rpc_connection() Connections W, S, J returns a QorusSystemAPIHelper to a remote Qorus instance
get_running_workflow_info() System Info W, S, J returns information about a running workflow execution instance
get_running_workflow_list() System Info W, S, J returns information about running workflow execution instances
get_service_info() System Info W, S, J returns information about a service
get_session_id() System Info W, S, J returns the current application session ID
get_sql_table() SQL Cache W, S, J retrieves an AbstractTable object from the SQL cache for DML operations
get_sql_cache_info() SQL Cache W, S, J returns information about the SQL cache
get_system_info() System Info W, S, J returns information about the system
get_system_service_info() System Info W, S, J returns information about a system service
get_user_connection() Connections W, S, J returns the given user connection object
get_user_service_info() System Info W, S, J returns information about a user service
get_value_map() Value Maps W, S, J retrieves a value mapping from a value map
get_value_maps() Value Maps W, S, J retrieves a list of all known value sets
log() logging W, S, J outputs a log message in the workflow's log file
next_sequence_value() Utility W, S, J returns the next value from the given datasource and database sequence
parse_uri_query() Utility W, S, J parses a URI query string in a URI path and returns the parsed data structure
post_sla_event_error() SLA W, S, J posts an unsuccessful event for SLA and performance tracking
post_sla_event_success() SLA W, S, J posts a successful event for SLA and performance tracking
post_sync_event() Utility W, S, J posts a workflow synchronization event given the event type name and event key
post_user_event() Utility W, S, J posts an application event of class OMQ::QE_CLASS_USER
prop_get() 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
prop_update() System Props W, S, J changes (inserts, updates, or deletes) the value of one or more system properties
qorus_get_local_url() System Info W, S, J returns a URL for the current system
raise_transient_alert() Alerts W, S, J raises a transient alert
restart_transaction() Utility W, S, J enables recovery from restartable DB communication errors
runtime_properties() System Info W, S, J returns information about runtime system defines defined
serialize_qorus_data() Utility W, S, J serializes Qore data structures to strings
set_option() Options W, S, J sets option values on a workflow, service, or job
wf_add_order_note() WF Misc W adds a note to a workflow order
wf_bind_event() WF Event W binds a workflow synchronization event to the current binds a workflow synchronization event to the current workflow synchronization event step
wf_bind_event_unposted() WF Event W binds an unposted workflow synchronization event to the current workflow synchronization event step
wf_bind_subworkflow() WF Sub W binds a subworkflow to the current subworkflow step
wf_delete_dynamic_data_key() WF Data W deletes a key in Workflow Dynamic Data
wf_delete_instance_data_key() WF Data W deletes a key in Workflow Execution Instance Data
wf_delete_sensitive_data() WF Data W deletes the sensitive data hash for the given sensitive data key and value
wf_delete_sensitive_data_key() 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
wf_delete_temp_data_key() WF Data W deletes a key in Workflow Temporary Order Data
wf_generate_unique_key() WF Misc W returns a unique key that can be used for an asynchronous step event key
wf_get_dynamic_data() WF Data W retrieves information from Workflow Dynamic Data
wf_get_error_info() WF Misc W returns information about the given workflow error
wf_get_instance_data() WF Data W retrieves information from Workflow Execution Instance Data
wf_get_order_keys() WF Misc W returns information about order keys associated with the current workflow order
wf_get_order_notes() WF Misc W retrieves notes saved against the workflow order
wf_get_parent_workflow_instanceid() WF Misc W returns the current workflow order's parent workflow_instanceid, if any
wf_get_sensitive_data() WF Data W retrieves the sensitive data hash for the given sensitive data key and value
wf_get_sensitive_data_from_alias() WF Data W retrieves the sensitive data hash for the given sensitive data alias
wf_get_sensitive_data_key_values() WF Data W retrieves a hash of sensitive data keys and values saved against the order
wf_get_static_data() WF Data W retrieves information from Workflow Static Order Data
wf_get_step_info() WF Misc W returns information about the current step
wf_get_step_status() WF Misc W returns information about the status of the given step
wf_get_temp_data() WF Data W retrieves information from Workflow Temporary Order Data
wf_get_workflow_instance_data() WF Data W retrieves information from the running workflow execution instance itself
wf_get_workflow_metadata() WF Misc W returns workflow metadata for the current workflow
wf_parent_wfiid() WF Misc W returns the order's parent workflow_instanceid, if any, otherwise returns NOTHING
wf_reschedule_order() WF Attach W changes the earliest possible processing date for the current workflow order instance in the attach function
wf_reprioritize_order() WF Misc W set the priority value of a workflow order instance
wf_set_blocked() WF Attach W sets the current workflow order instance to status OMQ::StatBlocked in the attach function
wf_set_retry_delay() WF Errors W sets the retry delay explicitly after raising an error against the workflow order instance with wf_serror()
wf_set_custom_status() WF Misc W sets a custom status value for the current workflow order data instance
wf_set_order_keys() WF Misc W sets order keys on the current workflow order instance
wf_serror() WF Errors W raises an error against the workflow order data without affecting the flow of processing
wf_skip_async_step() WF Async W skips setting an asynchronous key for an asynchronous step
wf_skip_event() WF Event W skips binding a workflow synchronization event to the current workflow synchronization event step
wf_skip_subworkflow() WF Sub W skips the subworkflow bind in a subworkflow step
wf_step_executed() WF Misc W verifies if a step has been executed on the current workflow order instance and has status COMPLETE
wf_submit_async_key() WF Async W submits an async key for an asynchronous step
wf_swarning() WF Errors W raises a warning against the workflow order data
wf_update_dynamic_data() WF Data W performs an update in Workflow Dynamic Data
wf_update_instance_data() WF Data W performs an update in Workflow Execution Instance Data
wf_update_sensitive_data() WF Data W performs an update in Sensitive Data
wf_update_sensitive_data_from_alias() WF Data W performs an update in Sensitive Data from a sensitive data alias
wf_update_temp_data() WF Data W performs an update in Workflow Temporary Order Data
wf_wfiid() WF Misc W returns the current order's workflow_instanceid

Workflow API Classes

The following classes are imported into workflow program logic containers:

Name 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

Workflow API Modules

The following modules are imported by default into 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 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
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):

Workflow Miscellaneous API

Miscellaneous workflow API functions:

Name Desc
wf_add_order_note() adds a note to a workflow order
wf_generate_unique_key() returns a unique key that can be used for an asynchronous step event key
wf_get_error_info() returns information about the given workflow error
wf_get_order_keys() returns information about order keys associated with the current workflow order
wf_get_order_notes() retrieves notes saved against the workflow order
wf_get_parent_workflow_instanceid() returns the current workflow order's parent workflow_instanceid, if any
wf_get_step_info() returns information about the current step
wf_get_step_status() returns information about the status of the given step
wf_get_workflow_metadata() returns workflow metadata for the current workflow
wf_parent_wfiid() returns the order's parent workflow_instanceid, if any, otherwise returns NOTHING
wf_reprioritize_order() set the priority value of a workflow order instance
wf_set_custom_status() sets a custom status value for the current workflow order data instance
wf_set_order_keys() sets order keys on the current workflow order instance
wf_step_executed() verifies if a step has been executed on the current workflow order instance and has status COMPLETE
wf_wfiid() returns the current order's workflow_instanceid

Workflow Data API

Functions related to workflow data (see Workflow Data):

Name Desc
wf_delete_dynamic_data_key() deletes a key in Workflow Dynamic Data
wf_delete_instance_data_key() deletes a key in Workflow Execution Instance Data
wf_delete_sensitive_data() deletes the sensitive data hash for the given sensitive data key and value
wf_delete_sensitive_data_key() deletes one or more keys from the workflow order data instance’s sensitive data hash for the given sensitive data key and value
wf_delete_temp_data_key() deletes a key in Workflow Temporary Order Data
wf_get_dynamic_data() retrieves information from Workflow Dynamic Data
wf_get_instance_data() retrieves information from Workflow Execution Instance Data
wf_get_sensitive_data() retrieves the sensitive data hash for the given sensitive data key and value
wf_get_sensitive_data_from_alias() retrieves the sensitive data hash for the given sensitive data alias
wf_get_sensitive_data_key_values() retrieves a hash of sensitive data keys and values saved against the order
wf_get_static_data() retrieves information from Workflow Static Order Data
wf_get_temp_data() retrieves information from Workflow Temporary Order Data
wf_get_workflow_instance_data() retrieves information from the running workflow execution instance itself
wf_update_dynamic_data() performs an update in Workflow Dynamic Data
wf_update_instance_data() performs an update in Workflow Execution Instance Data
wf_update_sensitive_data() performs an update in Sensitive Data
wf_update_sensitive_data() performs an update in Sensitive Data from a sensitive data alias
wf_update_temp_data() performs an update in Workflow Temporary Order Data

Workflow Error-Handling API

Functions related to workflow error handling:

Name Desc
wf_serror() raises an error against the workflow order data without affecting the flow of processing
wf_set_retry_delay() sets the retry delay explicitly after raising an error against the workflow order instance with wf_serror()
wf_swarning() raises a warning against the workflow order data

Workflow Async API

Functions that can only be called from asynchronous steps:

Name Desc
wf_skip_async_step() skips setting an asynchronous key for an asynchronous step
wf_submit_async_key() submits an async key for an asynchronous step

Workflow Subworkflow API

Functions that can only be called from subworkflow steps:

Name Desc
wf_bind_subworkflow() binds a subworkflow to the current subworkflow step
wf_skip_subworkflow() skips the subworkflow bind in a subworkflow step

Workflow Event Synchronization API

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

Name Desc
wf_bind_event() binds a workflow synchronization event to the current workflow synchronization event step
wf_bind_event_unposted() binds an unposted workflow synchronization event to the current workflow synchronization event step
wf_skip_event() skips binding a workflow synchronization event to the current workflow synchronization event step

Workflow Attach API

Functions that can only be called from the attach function:

Name Desc
wf_set_blocked() sets the current workflow order instance to status OMQ::StatBlocked in the attach function
wf_reschedule_order() changes the earliest possible processing date for the current workflow order instance in the attach function

Deprecated Workflow API Functions

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

Name Desc
bindSubWorkflow() replaced with wf_bind_subworkflow()
deleteDynamicDataKey() replaced with wf_delete_dynamic_data_key()
deleteInstanceDataKey() replaced with wf_delete_instance_data_key()
deleteTempDataKey() replaced with wf_delete_temp_data_key()
generateUniqueKey() replaced with wf_generate_unique_key()
getErrorInfo() replaced with wf_get_error_info()
getInstanceData() replaced with wf_get_instance_data()
getParentWorkflowInstanceID() replaced with wf_get_parent_workflow_instanceid()
getOrderInfo() deprecated; replaced with similar function wf_get_order_notes()
getWorkflowInstanceData() replaced with wf_get_workflow_instance_data()
setRetryDelay() replaced with wf_set_retry_delay()
getDynamicData() replaced with wf_get_dynamic_data()
getOrderKeys() replaced with wf_get_order_keys()
getStaticData() replaced with wf_get_static_data()
getStepInfo() replaced with wf_get_step_info()
getStepStatus() replaced with wf_get_step_status()
getTempData() replaced with wf_get_temp_data()
getWorkflowMetadata() replaced with wf_get_workflow_metadata()
reschedule_order() replaced with wf_reschedule_order()
reprioritize_order() replaced with wf_reprioritize_order()
serror() replaced with wf_serror()
setBlocked() replaced with wf_set_blocked()
setCustomStatus() replaced with wf_set_custom_status()
setOrderKeys() replaced with wf_set_order_keys()
setOrderInfo() deprecated; replaced with similar function wf_add_order_note()
skipAsyncStep() replaced with wf_skip_async_step()
skipSubWorkflow() replaced with wf_skip_subworkflow()
stepExecuted() replaced with wf_step_executed()
submitAsyncKey() replaced with wf_submit_async_key()
swarning() replaced with wf_swarning()
updateDynamicData() replaced with wf_update_dynamic_data()
updateInstanceData() replaced with wf_update_instance_data()
updateTempData() replaced with wf_update_temp_data()