Qorus Integration Engine®  4.0.3_git
Qorus Common Server API

This section covers APIs and API concepts common to all Qorus user code, workflows, services, and jobs for the Qore proggramming language.

For the Java common and workflow APIs, please see:

Qorus System Utility Classes

The following Qore modules are imported into all user objects:

Name Description
json provides APIs for JSON data serialization and deserialization support
Mime provides MIME definitions and functionality
Mapper provides a data-mapping API
SoapClient provides a SOAP client API
SqlUtil provides high-level APIs for programmatic DML (SQL data manipulation), DDL (creating, querying, manipulating database definitions), and DBA operations
TableMapper provides high-level APIs for mapping data to and from database tables
Util provides utility APIs
uuid provides an API for generating UUIDs
xml provides APIs for parsing, validating, and generating XML documents
yaml provides APIs for Qore's YAML-based data serialization and deserialization support

The following classes are imported into all user objects:

Qore Class Java Class Description
AbstractFsRemoteReceive AbstractFsRemoteReceive provides an API for streaming data from a remote filesystem through a remote Qorus instance
AbstractParallelStream n/a 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 DbRemote provides an API wrapper for all system.sqlutil service methods
DbRemoteReceive DbRemoteReceive provides an API for streaming data from a remote database through a remote Qorus instance
DbRemoteSend DbRemoteSend provides an API for streaming data to a remote database through a remote Qorus instance
FsRemote FsRemote provides an API wrapper for all system.fs service methods
FsRemoteSend FsRemoteSend provides an API for streaming data to a remote filesystem through a remote Qorus instance
QorusInboundTableMapper InboundTableMapper provides an API for mapping data to a DB table
QorusInboundTableMapperIterator n/a provides an iterator-based API for mapping data to a DB table
QorusRawSqlStatementOutboundMapper RawSqlStatementOutboundMapper provides an API for mapping from SQL statement using direct SQL statements passed in
QorusRemoteServiceHelper n/a provides an API for calling service methods in remote Qorus instances
QorusSqlStatementOutboundMapper SqlStatementOutboundMapper provides an API for mapping from SQL statement using SqlUtil
QorusSystemAPIHelper n/a provides an API for calling RPC API methods in remote Qorus instances
OMQ::QorusSystemRestHelper QorusSystemRestHelper provides an API for using the REST API in remote Qorus instances

Qorus Logging Functions

Qore Method Java Method Qore Function Description
JobApi::log() JobApi.log() log() outputs information in the relevant log file

Qorus System Information API

Qore Method Java Method Qore Function Description
UserApi::getActiveJobs() UserApi.getActiveJobs() get_active_jobs() returns information about active jobs
UserApi::getGlobalConfigItemValue() UserApi.getGlobalConfigItemValue() n/a returns the value of the given configuration item on global level
UserApi::getRunningWorkflowInfo() UserApi.getRunningWorkflowInfo() get_running_workflow_info() returns information about a running workflow execution instance
UserApi::getRunningWorkflowList() UserApi.getRunningWorkflowList() get_running_workflow_list() returns information about running workflow execution instances
UserApi::getServiceInfo() UserApi.getServiceInfo() get_service_info() returns information about a service
UserApi::getSessionId() UserApi.getSessionId() get_session_id() returns the current application session ID
UserApi::getSystemInfo() UserApi.getSystemInfo() get_system_info() returns information about the system
UserApi::getSystemServiceInfo() UserApi.getSystemServiceInfo() get_system_service_info() returns information about a system service
UserApi::getUserServiceInfo() UserApi.getUserServiceInfo() get_user_service_info() returns information about a user service
UserApi::qorusGetLocalUrl() UserApi.qorusGetLocalUrl() qorus_get_local_url() returns a URL for the current system
UserApi::runtimeProperties() UserApi.runtimeProperties() runtime_properties() returns information about runtime system defines

Qorus System Connection API

Qore Method Java Method Qore Function Description
UserApi::getDatasourceDedicated() n/a get_datasource_dedicated() returns a dedicated Qore::SQL::Datasource object
UserApi::getDatasourcePool() UserApi.getDatasourcePool() get_datasource_pool() returns a shared Qore::SQL::DatasourcePool object
UserApi::getRemoteRestConnection() UserApi.getRemoteRestConnection() get_remote_rest_connection() returns a QorusSystemRestHelper to a remote Qorus instance
UserApi::getRemoteRpcConnection() n/a get_remote_rpc_connection() returns a QorusSystemAPIHelper to a remote Qorus instance
UserApi::getUserConnection() UserApi.getUserConnection() get_user_connection() returns the given user connection object

Qorus High-Level Streaming API

The following classes provide Work with Data Streaming to iterate with remote Qorus instances

Qore Class Java Class Description
AbstractFsRemoteReceive AbstractFsRemoteReceive provides an API for streaming data from a remote filesystem through a remote Qorus instance
AbstractParallelStream n/a 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 DbRemote provides an API wrapper for all system.sqlutil service methods
DbRemoteReceive DbRemoteReceive provides an API for streaming data from a remote database through a remote Qorus instance
DbRemoteSend DbRemoteSend provides an API for streaming data to a remote database through a remote Qorus instance
FsRemote FsRemote provides an API wrapper for all system.fs service methods
FsRemoteSend FsRemoteSend provides an API for streaming data to a remote filesystem through a remote Qorus instance

Qorus SQL Object Cache API

Qore Method Java Method Qore Function Description
UserApi::clearSqlTableCache() UserApi.clearSqlTableCache() clear_sql_table_cache() clears a cached table from the SQL cache
UserApi::getSqlTable() UserApi.getSqlTable() get_sql_table() retrieves an AbstractTable object from the SQL cache for DML operations
UserApi::getSqlCacheInfo() UserApi.getSqlCacheInfo() get_sql_cache_info() returns information about the SQL cache

Qorus Value Map API

The following functions provide APIs to work with Qorus Value Maps

Qore Method Java Method Qore Function Description
UserApi::getValueMap() UserApi.getValueMap() get_value_map() retrieves a value mapping from a value map
UserApi::getValueMaps() UserApi.getValueMaps() get_value_maps() retrieves a list of all known value sets

Qorus System Alert APIs

Qore Method Java Method Qore Function Description
UserApi::raiseTransientAlert() UserApi.raiseTransientAlert() raise_transient_alert() raises a transient alert

Qorus System Auditing APIs

Qore Method Java Method Qore Function Description
UserApi::auditCheckEventString() UserApi.auditCheckEventString() audit_check_event_string() checks if the given audit event (given as a string) is enabled
UserApi::auditCheckEvent() UserApi.auditCheckEvent() audit_check_event() checks if the given audit event (given as an integer code) is enabled
UserApi::auditGetMask() UserApi.auditGetMask() audit_get_mask() returns the audit event mask
UserApi::auditUserEvent() UserApi.auditUserEvent() audit_user_event() creates a user audit event (with audit event code OMQ::AE_USER_EVENT) against the workflow, service, or job instance

Qorus System Option APIs

Qore Method Java Method Qore Function Description
UserApi::getOption() see interface API classes get_option() returns the value of one or more system or interface options
UserApi::getQorusOptions() UserApi.getQorusOptions() get_qorus_options() returns the value of system options
UserApi::getQorusOptionsArgs() UserApi.getQorusOptionsArgs() get_qorus_options_args() returns the value of system options
UserApi::getQorusOptionInfo() UserApi.getQorusOptionInfo() get_qorus_option_info() returns information about system options
UserApi::getQorusOptionInfoArgs() UserApi.getQorusOptionInfoArgs() get_qorus_option_info_args() returns information about system options
UserApi::setOption() see interface API classes set_option() sets option values on a workflow, service, or job

Qorus System Property APIs

Qore Method Java Method Qore Function Description
UserApi::propGet() UserApi.propGet() prop_get() returns the value of the given system property key in the given domain or NOTHING if the system property does not exist
UserApi::propUpdate() UserApi.propUpdate() prop_update() changes (inserts, updates, or deletes) the value of one or more system properties

Qorus System General Utility APIs

Qore Method Java Method Qore Function Description
UserApi::callNetworkApi() UserApi.callNetworkApi() call_network_api() calls a system RPC API with system permissions
UserApi::callNetworkApiArgs() UserApi.callNetworkApiArgs() call_network_api_args() calls a system RPC API with system permissions with an explicit argument list argument
UserApi::callNetworkApiArgsWithAuthentication() UserApi.callNetworkApiArgsWithAuthentication() call_network_api_args_with_authentication() calls a system RPC API with authentication information (username and password)
UserApi::callRestApi() UserApi.callRestApi() call_rest_api() calls a system REST API with system permissions
UserApi::callRestApiWithAuthentication() UserApi.callRestApiWithAuthentication() call_rest_api_with_authentication() call a system REST API with authentication information (username and password)
UserApi::createOrder() UserApi.createOrder() create_order() creates a workflow order data instance in the database and returns the workflow_instanceid of the order created
UserApi::createRemoteOrder() UserApi.createRemoteOrder() create_remote_order() creates a workflow order data instance in a remote Qorus instance and returns the workflow_instanceid of the order created
UserApi::deserializeQorusData() UserApi.deserializeQorusData() deserialize_qorus_data() deserializes strings to Qore data structures
UserApi::execSynchronousWorkflow() UserApi.execSynchronousWorkflow() exec_synchronous_workflow() executes a workflow order synchronously and returns the result of execution
UserApi::getNextSequenceValue() UserApi.getNextSequenceValue() next_sequence_value() returns the next value from the given datasource and database sequence
UserApi::sleep() UserApi.sleep() omqsleep() safely pause execution for a defined period of time
UserApi::sleep() UserApi.usleep() omqusleep() safely pause execution for a defined period of time
UserApi::postSyncEvent() UserApi.postSyncEvent() post_sync_event() posts a workflow synchronization event given the event type name and the unique event key
UserApi::postUserEvent() UserApi.postUserEvent() post_user_event() posts an application event of class OMQ::QE_CLASS_USER
UserApi::restartTransaction() UserApi.restartTransaction() restart_transaction() enables recovery from restartable DB communication errors
UserApi::serializeQorusData() UserApi.serializeQorusData() serialize_qorus_data() serializes Qore data structures to strings

Qorus System SLA APIs

Qore Method Java Method Qore Function Description
UserApi::flushSlaEvents() UserApi.flushSlaEvents() flush_sla_events() flushes all pending SLA events to the DB
UserApi::postSlaEventError() UserApi.postSlaEventError() post_sla_event_error() posts an unsuccessful SLA and performance tracking event
UserApi::postSlaEventSuccess() UserApi.postSlaEventSuccess() post_sla_event_success() posts a successful SLA and performance tracking event

Qorus System Building Block APIs

Qore Method Java Method Description
UserApi::expandOneVariable() UserApi.expandOneVariable() expands one variable in a templated string
UserApi::expandTemplatedValue() UserApi.expandTemplatedValue() expands all variables in a templated string
UserApi::bbParseExactlyOneVariable() UserApi.bbParseExactlyOneVariable() parses one template variable and returns a hash with its parts
UserApi::getInputData() UserApi.getInputData() returns input data
UserApi::updateOutputData() UserApi.updateOutputData() updates output data
Note
all functions in the Util module are available in all user code objects in Qorus as well.

Calling Qorus Services

Qorus services can be called from anywhere in Qorus user code (from a workflow, from another service, or in a job). To call a service from Qore, use the ::omqservice object imported into every workflow, service, and job program object as follows:

omqservice.[system|user].<service_name>.<method_name>(<arguments>)

For example, to get information about a workflow order from its order key:

hash<auto> props = omqservice.system.info.searchOrderKeys(("value": "keyvalue"));

To call a service method from Java, use the UserApi.callRestApi() method as in the following example:

Object result = UserApi.callRestApi("PUT", "services/service-name/method/call", args);

Config Item / Building Block Template Substitution Strings

Template substitution strings in building block APIs have one of the following formats:

  • $type:value
  • $type:{value}

Values may be enclosed in square brackets to separate value characters from other characters that might otherwise be considered part of the value string.

Value characters for values are alphanumeric characters, plus underscore ("_"), and the dot (".") character to reference hash members. Value strings enclosed in curly brackets ('{}') can be any character except a close curly bracket ('}').

Note
Dot (".") characters may be escaped with a backslack character ("\\") before the dot to ensure that the dot is used as a part of the string and not a field separator; ex: "field\.with\.dots"

Valid types and values are given in the following table.

Template Substitution String Values

Context Type Value Data Type Read/Write Example Description
all config any any R $config:item_name the value of the given configuration item
all local type string R $local:type the interface type: "workflow", "service", or "job"
all local name string R $local:name the interface name
all local version string R $local:version the interface version
all local id int R $local:id the interface ID
all timestamp @ref date_formatting "date format" string R $timestamp:{YYYY-MM-DD HH:mm:SS.xx Z} a timestamp formatted according to the value as the format argument (see Date Formatting Codes for more information on the timestamp format argument)
job info any any RW $info:key the value of the given key in the job's info hash
job local job_instanceid int R $local:job_instanceid the job instance ID
job state any any RW $state:key the value of the given key in the job's state hash
service local servicetype string R $local:servicetype the service type: "user" or "system"
service state any any RW $state:key the value of the given key in the service's state hash
workflow dynamic any any RW $dynamic:order.ID the given value from the workflow order's dynamic data hash; dot notation accepted
workflow feedback any any W $feedback:key provides the name of the key that the given output data value will be saved to in the parent order; only valid for child orders in a subworkflow hierarchy; each feedback key value is subject to recursive template substitution with UserApi::expandTemplatedString()
workflow keys any any RW $keys:order_id the value of the given workflow order key; each orde key value is subject to recursive template substitution with UserApi::expandTemplatedString()
workflow local execid int R $local:execid the workflow execution instance ID
workflow local stepname string R $local:stepname the step name
workflow local stepversion string R $local:stepversion the step version
workflow local stepid int R $local:stepid the step ID
workflow local ind int R $local:ind the step index value
workflow local workflow_instanceid int R $local:workflow_instanceid the workflow instance ID
workflow sensitive skey.svalue.... any RW $sensitive:taxid.xxxx.address the given value from the workflow order's sensitive data hash; dot notation accepted; the first two components of the value are the sensitive data key and the sensitive data value
workflow sensitive-alias alias.... any RW $sensitive-alias:{cust-1.address} the given value from the workflow order's sensitive data hash with the given alias; dot notation accepted; the first component of the value is the sensitive data alias value
workflow static any any R $static:order.ID the given value from the workflow order's static data hash; dot notation accepted
workflow step any any RW $step:{order-data.address} the given value from the current step's step data hash; dot notation accepted
Note
  • in each of the examples above the value could be encosed in curly brackets, ex: "$static:{step.order.address}"; strings with characters outside the acceptable range ([a-zA-Z_0-9]) must be enclosed with curly brackets; ex: "$static:{account-1.customer-name}"
  • most template strings are readable meaning they can be used in any context where template variable substitution is performed; writable template strings marked with W above can also be used with UserApi::updateOutputData()