Qorus Integration Engine®  5.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::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}

In addition, each template substitution string can be followed by an expression giving an alternate value to use in case the first expression returns no value in the following format:

  • ??{...} where ... is a template substitution expression to use if the first expression resolves to no 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 ('}').

Examples:

  • Use the Account.Name value from static data
    $static:{Account.Name} 
  • Take the Account.Address.Country value from static data, if not present, use the string "USA"
    $static:{Account.Address.Country}??{USA} 
  • Take the Account.ShippingAddress value from static data, if not present, use the Account.BillingAddress value instead
    $static:{Account.ShippingAddress}??{$static:{Account.BillingAddress}} 
  • Use the first expression in the list that has a value
    $static:FullName??{$static:LegalName}??${static:Name} 
Note
  • Dot (".") characters may be escaped with a backslach 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"
  • Template substitution is performed recursively and template strings are tokenized for processing; to prohibit template substitution, escape the first "$" character of template strings with a backslash ("\\"); ex "\$static:not_a_template_string"
  • If intermediate elements when resolving a path are lists of data structures, and the path is resolved through the list, the resulting value will be a list of all resolved elements in the path

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 for the current context (see also $xconfig: below)
all config * *hash R $config:* the value of all configuration items as a hash keyed by item name for the current context (see also $xconfig: below)
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 local * *hash R $local:* the entire local context hash
all parse-value any any R $parse-value:{id=$static:{account.id}} parses the string argument with parse_to_qore_value() after recursive template substitution
all pstate any any RW $pstate:key the value of the given key in the interface's persistent state hash; see Universal Persistent Storage
all pstate * *hash R $pstate:* the entire interface persistent state hash; see Universal Persistent Storage
all python-expr any any R $python-expr:{("$info:type" + "." + "$info:name" + " v" + "$info:version")} Performs template substitution on the argument and then parses the argument as a Python expression; the evaluation of the expression is used as the resulting value
all qore-expr any any R $qore-expr:{("$info:type" + "." + "$info:name" + " v" + "$info:version")} Performs template substitution on the argument and then parses the argument as a Qore expression; the evaluation of the expression is used as the resulting value
all qore-expr-value any string R $qore-expr-value:{$static:{order.json}} Returns a string representation of the value that can be used with $qore-expr:{}; strings are quoted (and internal strings are escaped), other values are converted to valid Qore expressions
all rest REST URI path any R $rest:{remote/user/my-connection/url_hash/path} the result of a GET request to the given system API URI path in the latest REST API
all timestamp timegm int R $timestamp:timegm returns the current number of seconds after the UNIX epoch (1970-01-01 UTC)
all timestamp 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)
all transient any any RW $transient:{account-info.id} the value from the temporary thread-local transient data hash; see The Difference Between var and transient Data
all transient * *hash R $transient:* the entire temporary transient data hash; see The Difference Between var and transient Data
all var any any RW $var:{account-info.id} the value from the temporary thread-local/block-local data hash; see The Difference Between var and transient Data
all var * *hash R $var:* the entire temporary thread-local/block-local data hash; see The Difference Between var and transient Data
all xconfig any any R $xconfig:item_name the value of the given configuration item for the current interface context; in data pipelines and finite state machines, this will return configuration information for the interface and not for the data pipeline or finite state machine (see also $config: above)
all xconfig * *hash R $xconfig:* the value of all configuration items as a hash keyed by item name for the current interface context; in data pipelines and finite state machines, this will return configuration information for the interface and not for the data pipeline or finite state machine (see also $config: above)
job info any any RW $info:key the value of the given key in the job info hash (return value of JobApi::getInfo())
job info * *hash R $info:* the entire job info hash (return value of JobApi::getInfo())
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 (used for recovery state; cleared when the job gets a COMPLETE status)
job state * *hash R $state:* the entire job state hash (used for recovery state; cleared when the job gets a COMPLETE status)
service info any any RW $info:key the value of the given key in the service info hash (return value of ServiceApi::getServiceInfo())
service info * *hash R $info:* the entire job info hash (return value of ServiceApi::getServiceInfo())
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
service state * *hash R $state:* the entire service 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 dynamic * *hash R $dynamic:* the entire dynamic data hash
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::expandTemplatedValue()
workflow info any any RW $info:key the value of the given key in the workflow info hash with an additional step key containing the return value of WorkflowApi::getStepInfo()
workflow info * *hash R $info:* the entire hash consisting of the workflow info hash with an additional step key containing the return value of WorkflowApi::getStepInfo()
workflow keys any any RW $keys:order_id the value of the given workflow order key; each order key value is subject to recursive template substitution with UserApi::expandTemplatedValue()
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 static * *hash R $static:* the entire static data hash
workflow step any any RW $step:{order-data.address} the given value from the current step's step data hash; dot notation accepted
workflow step * *hash R $step:* the entire step data hash
workflow temp any any RW $temp:order.ID the given value from the workflow order's temporary data hash; dot notation accepted
workflow temp * *hash R $temp:* the entire temporary data hash
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()

Universal Persistent Storage

$pstate: can be used for persistent storage in any interface:

  • for workflows, $pstate: is equal to $dynamic:
  • for services, $pstate: is unique persistent storage for services
  • for jobs, $pstate: is unique and different to $state: data, which is purged when a job instance gets a COMPLETE status

$pstate: is serialized and stored in the database when updated and therefore is persistent across Qorus restarts.

The Difference Between var and transient Data

$transient: differs from $var: in that each block in a finite state machine has its own copy of $var: data, while $transient: data is persistent in a single interface action across finite state machine blocks.

File Locations

The following location types are supported:

  • file://file_location
    • file_location: gives the file location; environment variable substitution is performed
    • ex: file://$OMQ_DIR/user/file.txt
  • ftp(s)://host[:port]/path
    • ex: ftps://my.host:8888/path/file
  • http(s)://host[:port]/uri_path
    • ex: https://my.host:8888/path/file
  • resource://[[remote:]service:]resource_path
  • sftp://host[:port]/path
    • ex: sftp://my.host:8888/path/file
Note
ftps (FTP Secure) is not the same as sftp (SSH FTP).

Locations are used in the following APIs:

Note
service: is not required in resource:// locations when the resource is retrieved from the same service; in this case the given resource will be retrieved from the current service, however in all other cases, service: is required or a LOCATION-ERROR exception will be thrown.
Object
const Object