Qorus Common Server API

Table of Contents

• Qorus System Utility Classes
• Qorus Logging Functions
• Qorus System Information API
• Qorus System Connection API
• Qorus High-Level Streaming API
• Qorus SQL Object Cache API
• Qorus Value Map API
• Qorus System Alert APIs
• Qorus System Auditing APIs
• Qorus System Option APIs
• Qorus System Property APIs
• Qorus System General Utility APIs
• Qorus System SLA APIs
• Qorus System Building Block APIs
• Calling Qorus Services
• Config Item / Building Block Template Substitution Strings
  • Universal Persistent Storage
  • The Difference Between var and transient Data
• File Locations

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:

• UserApi

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::executeFsm()	UserApi.executeFsm()	n/a	executes a finite state machine registered with the interface and returns the result
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::registerFsmAsObserver()	UserApi.registerFsmAsObserver()	n/a	registers a finite state machine as an event observer
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	R	$info:key	the value of the given key in the job info hash (return value of JobApi::getInfo()) Note supported for backwards-compatibility for writing as an alias to $jinfo
job	info	*	*hash	R	$info:*	the entire job info hash (return value of JobApi::getInfo())
job	jinfo	any	any	RW	$info:key	the value of the given key in the job result info hash (value set in JobApi::saveInfo())
job	jinfo	*	*hash	R	$info:*	the entire job result info hash (value set in JobApi::saveInfo())
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
  • [remote:]: gives the name of an optional remote Qorus connection
  • [service:]: gives the name of the service that has the given service file resource
    • ex: resource://my-service:resource-path/resource-name.html
• 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:

• Python: UserApi.getBinaryFileFromLocation()
• Python: UserApi.getTextFileFromLocation()
• Java: UserApi.getBinaryFileFromLocation()
• Java: UserApi.getTextFileFromLocation()
• Qore: UserApi::getBinaryFileFromLocation()
• Qore: UserApi::getTextFileFromLocation()

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.