Qorus Integration Engine®  4.0.3_git
OMQ::UserApi::UserApi Class Reference

main common Qorus API class More...

Inheritance diagram for OMQ::UserApi::UserApi:
OMQ::UserApi::Job::JobApi OMQ::UserApi::Service::ServiceApi OMQ::UserApi::Workflow::WorkflowApi OMQ::UserApi::Workflow::QorusWorkflow

Static Public Member Methods

static *hash< auto > getUserServiceInfo (string name)
 returns information about the given user service (if it's currently loaded) More...
 
static SqlUtil::AbstractTable getSqlTable (string datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static SqlUtil::AbstractTable getSqlTable (AbstractDatasource datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static hash< auto > getSqlCacheInfo ()
 get information about cached object More...
 
static clearSqlTableCache (string datasource, *string table_name)
 clears all objects for given datasource from the cache (for example, if database objects have been updated in the dataserver) More...
 
static clearSqlTableCache (AbstractDatasource datasource, *string table_name)
 clears cached objects for given datasource (for example, if database objects have been updated in the dataserver) More...
 
static auto getValueMap (string mapname, string key)
 Gets a lookup value from the value map by a key; the value map must be registered to the current interface. More...
 
static list< auto > getValueMaps ()
 Gets all value maps valid for the current interface. More...
 
static bool postSlaEventSuccess (string sla, number value)
 posts a successful SLA event for SLA monitoring and performance tracking More...
 
static bool postSlaEventError (string sla, number value, string err, string desc)
 posts an unsuccessful SLA event for SLA monitoring and performance tracking More...
 
static flushSlaEvents ()
 flushes all pending SLA events to disk and returns after the data has been committed More...
 
static *hash< auto > getSystemServiceInfo (string name)
 returns information about the given system service (if it's currently loaded) More...
 
static *hash getServiceInfo (string type, string name)
 returns information about the given service (if it's currently loaded) More...
 
static list getRunningWorkflowList (*string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances More...
 
static hash getRunningWorkflowInfo (softint id)
 returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not More...
 
static softint createOrder (string name, *string version, hash params, string status=StatReady)
 creates a workflow order data instance in the database More...
 
static softint createRemoteOrder (string remote, string name, *string version, hash params, string status=StatReady, bool register_dependency=True)
 creates a workflow order data instance in a remote Qorus instance More...
 
static hash< auto > execSynchronousWorkflow (string name, *string version, hash sdata, *hash opts, *hash ddata, softint priority=DefaultOrderPriority, *hash orderkeys, *softstring external_order_instanceid, *softint parent_workflow_instanceid)
 executes a workflow order synchronously and returns the final status and order ID in a hash More...
 
static int postUserEvent (string severity, auto info)
 posts an application event of class QE_CLASS_USER More...
 
static hash runtimeProperties ()
 returns Qorus runtime properties as a hash More...
 
static auto callNetworkApiArgsWithAuthentication (string user, string pass, string call, softlist args)
 calls a system RPC API with authentication information (username and password) More...
 
static auto callNetworkApiArgs (string call, softlist args)
 calls a system RPC API with the argument list to the API method as a top-level argument to this method; the API is called with system permissions (no restrictions) More...
 
static auto callNetworkApi (string call)
 calls a system RPC API and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApi (string method, string path, *hash< auto > body_args)
 calls a system REST API method and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApiWithAuthentication (string user, string pass, string method, string path, *hash< auto > body_args)
 calls a system REST API method with authentication information (username and password) and returns the result More...
 
static hash getSystemInfo ()
 returns a hash of system info More...
 
static int getSessionId ()
 returns the current Qorus application session ID More...
 
static logFatal (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logError (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logWarn (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logInfo (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logDebug (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logTrace (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsFatal (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsError (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsWarn (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsInfo (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsDebug (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsTrace (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static *int auditUserEvent (string user_event, *string info1, *string info2)
 creates a user audit event (with audit event code AE_USER_EVENT) against the workflow, service, or job instance More...
 
static bool auditCheckEventString (string opt)
 checks if the given audit event (given as a string) is enabled More...
 
static bool auditCheckEvent (softint opt)
 checks if the given audit event (given as an integer code) is enabled More...
 
static int auditGetMask ()
 returns the audit event mask More...
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds More...
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static auto getQorusOptions ()
 returns the value of the given system option or options More...
 
static hash< auto > getQorusOptionInfo ()
 returns a hash giving information about system options More...
 
static hash< auto > getQorusOptionInfoArgs (*list< auto > args)
 returns a hash giving information about system options More...
 
static auto getQorusOptionsArgs (softlist args)
 returns the value of the given system option or options More...
 
static hash< auto > getActiveJobs ()
 Returns information on all active jobs visible to the calling user. More...
 
static object getUserConnection (string name, bool connect=True, bool register_dependency=True, *hash< auto > rtopts)
 Returns an object corresponding to a defined user connection. More...
 
static Qore::SQL::Datasource getDatasourceDedicated (string name, bool register_dependency=True)
 returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions More...
 
static AbstractDatasource getDatasourcePool (string name, bool register_dependency=True)
 returns a DatasourcePool object for the given datasource name More...
 
static hash< auto > getDatasourceInfo (string name)
 returns a hash of information for the given datasource, if known, otherwise throws an exception More...
 
static QorusSystemAPIHelper getRemoteRpcConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus remote connection. More...
 
static QorusSystemRestHelper getRemoteRestConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemRestHelper object corresponding to a defined Qorus remote connection. More...
 
static raiseTransientAlert (string alert, string reason, *hash< auto > info)
 raises a transient system alert from a workflow, service, or job More...
 
static string qorusGetLocalUrl (*string username, *string password)
 returns a string giving the local system URL More...
 
static setOption (hash< auto > hash)
 Changes option values on a workflow, service, or job. More...
 
static auto getOption ()
 Returns the value of the named workflow, service, or job option or options. More...
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named workflow, service, or job option or options. More...
 
static hash< auto > blockOrder (softint wfiid)
 block the given workflow order data instance More...
 
static hash< auto > unblockOrder (softint wfiid, *hash< auto > tempdata, *hash< auto > orderkeys)
 unblocks the given workflow order data instance More...
 
static hash< auto > cancelOrder (softint wfiid)
 cancel the given workflow order data instance More...
 
static hash< auto > uncancelOrder (softint wfiid, *hash< auto > tempdata)
 uncancels the given workflow order data instance More...
 
static *hash< auto > getUserContextInfo ()
 returns a hash for the current user context More...
 
static auto getConfigItemValue (string cfg_item, *hash< auto > local_context)
 returns config item value in the current user context More...
 
static auto getGlobalConfigItemValue (string item, *hash< auto > local_context)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static auto getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static Mapper::Mapper getMapper (string name, *hash< auto > rtopts)
 returns the given mapper if registered for the current interface More...
 
static Qore::AbstractIterator getMapperIterator (string name, Qore::AbstractIterator input, *hash< auto > rtopts)
 returns an iterator for the named mapper using the iterator argument for input More...
 
static bool postSyncEvent (string eventtype, string eventkey)
 posts a workflow synchronization event given the event type name and the unique event key More...
 
static hash< auto > propGet ()
 returns a hash of all system properties in all domains More...
 
static *hash< auto > propGet (string domain)
 returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist More...
 
static auto propGet (string domain, string key)
 returns the value of the given system property key in the given domain or NOTHING if the system property does not exist More...
 
static string propUpdate (string domain, softstring key, auto value)
 changes (inserts, updates, or deletes) the value of a single system property More...
 
static hash< auto > propUpdate (hash< auto > h)
 changes (inserts, updates, or deletes) the value of one or more system properties according to a hash argument More...
 
static softint getNextSequenceValue (AbstractDatasource ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static softint getNextSequenceValue (string ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static string serializeQorusData (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static string serializeQorusDataWithNothing (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static auto deserializeQorusData (string data)
 parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data More...
 
static auto deserializeQorusData (null data)
 deserializing a NULL value from the DB returns no value
 
static *string restartTransaction (string driver, hash< auto > ex)
 returns a string error message if any exception in the chain passed was caused by a recoverable DB error, otherwise returns NOTHING More...
 
static bool isInternalSystemDebuggingEnabled ()
 returns True if internal system debugging is enabled
 
static auto getHashDotValue (*hash< auto > var_data, string var_name)
 returns the value of the given key from the given hash, respects dot notation in the key name More...
 
static auto expandOneVariable (string str, string var_context, string var_name, *hash< auto > local_context, *bool brackets)
 expands one variable in a templated string More...
 
static bool isSingleTemplatedString (auto value)
 checks if the given value is a templated string with only one expandable variable More...
 
static auto expandTemplatedValue (auto value, *hash< auto > local_context)
 expands all variables in a templated string More...
 
static hash< BbVariable > bbParseExactlyOneVariable (string str)
 parses one template variable and returns a hash with its parts More...
 
static auto getInputData (string field_name, *hash< auto > local_context, *hash< auto > input_data_cfg)
 returns specified input data field's value More...
 
static hash< auto > getInputData (*hash< auto > input_data_cfg, *hash< auto > local_context)
 returns all input data More...
 
static *hash< auto > updateHashDotValue (*hash< auto > var_data, string var_name, auto value)
 updates the given hash with a key in dot notation with the given value More...
 
static updateOutputData (string field_name, auto output_data, *hash< auto > output_data_cfg)
 updates specified output data field's value More...
 
static updateOutputData (hash< auto > all_output_data, hash< auto > output_data_cfg=UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY))
 updates all output data More...
 
static string getTextFileFromLocation (string location)
 returns string data for the given file location More...
 
static binary getBinaryFileFromLocation (string location)
 returns binary data for the given file location More...
 

Detailed Description

main common Qorus API class

Since
Qorus 4.0

Member Function Documentation

◆ auditCheckEvent()

static bool OMQ::UserApi::UserApi::auditCheckEvent ( softint  opt)
static

checks if the given audit event (given as an integer code) is enabled

Parameters
optthe audit event code to check; see Audit Event Codes for possible values
Returns
True if the event is audited, False if not
See also
audit_check_event()

◆ auditCheckEventString()

static bool OMQ::UserApi::UserApi::auditCheckEventString ( string  opt)
static

checks if the given audit event (given as a string) is enabled

Parameters
optthe audit event code to check; see Audit Event Strings for possible values
Returns
True if the event is audited, False if not
Exceptions
AUDIT-EVENT-ERRORthe given audit event string does not exist
See also
audit_check_event_string()

◆ auditGetMask()

static int OMQ::UserApi::UserApi::auditGetMask ( )
static

returns the audit event mask

Returns
the audit event mask
See also
audit_get_mask()

◆ auditUserEvent()

static *int OMQ::UserApi::UserApi::auditUserEvent ( string  user_event,
*string  info1,
*string  info2 
)
static

creates a user audit event (with audit event code AE_USER_EVENT) against the workflow, service, or job instance

Parameters
user_eventthe user event code string
info1optional informational string for the AUDIT_EVENTS.INFO1 field
info2optional informational string for the AUDIT_EVENTS.INFO2 field
Returns
NOTHING if user event auditing is not enabled (see system option qorus.audit), or the integer audit event id
Note
nothing will be written to the AUDIT_EVENTS table if the qorus.audit system option does not include the "user-events" (AO_USER_EVENTS) option; in case this is not set, the call will have no effect
See also
audit_user_event()

◆ bbParseExactlyOneVariable()

static hash<BbVariable> OMQ::UserApi::UserApi::bbParseExactlyOneVariable ( string  str)
static

parses one template variable and returns a hash with its parts

Parameters
strtemplated string to be parsed (has to contain exactly one variable and nothing more); see Config Item / Building Block Template Substitution Strings for more information on this parameter
Returns
BbVariable hash representing the variable
Exceptions
FORMAT-ERRORif the templated string doesn't have correct format
Since
Qorus 4.0.3

◆ blockOrder()

static hash<auto> OMQ::UserApi::UserApi::blockOrder ( softint  wfiid)
static

block the given workflow order data instance

Parameters
wfiidthe workflow order instance ID to block
Returns
a hash with the following key:
  • workflow_status: the status of the workflow order

An exception will be thrown if the status is OMQ::StatInProgress

Exceptions
BLOCK-WORKFLOW-ERRORinvalid status, foreign session id, missing original status, uncancel operation already in progress
See also
block_order()

◆ callNetworkApi()

static auto OMQ::UserApi::UserApi::callNetworkApi ( string  call)
static

calls a system RPC API and returns the result; the API is called with system permissions (no restrictions)

include any arguments after the method name, ex:

UserApi::callNetworkApi("omq.system.exec-synchronous-existing", ("workflow_instanceid": wfiid));
Parameters
callthe full RPC API method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
Returns
the return value of the method
See also
call_network_api_args_with_authentication() to call with the permissions as a specific user
call_network_api_args()
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
See also

◆ callNetworkApiArgs()

static auto OMQ::UserApi::UserApi::callNetworkApiArgs ( string  call,
softlist  args 
)
static

calls a system RPC API with the argument list to the API method as a top-level argument to this method; the API is called with system permissions (no restrictions)

Parameters
callthe full RPC API method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
argsany arguments to the method; if multiple argument should be passed to the method, use a list of arguments here
Returns
the return value of the method
See also
call_network_api_args_with_authentication() to call with the permissions as a specific user
call_network_api()
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
See also

◆ callNetworkApiArgsWithAuthentication()

static auto OMQ::UserApi::UserApi::callNetworkApiArgsWithAuthentication ( string  user,
string  pass,
string  call,
softlist  args 
)
static

calls a system RPC API with authentication information (username and password)

Parameters
userthe username to use for the call
passthe password to use for the call
callthe full RPC API method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
argsany arguments to the method; if multiple argument should be passed to the method, use a list of arguments here
Returns
the return value of the method
See also
call_network_api_args()
call_network_api()
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
See also

◆ callRestApi()

static auto OMQ::UserApi::UserApi::callRestApi ( string  method,
string  path,
*hash< auto >  body_args 
)
static

calls a system REST API method and returns the result; the API is called with system permissions (no restrictions)

Example:
int pid = UserApi::callRestApi("GET", "system/pid");
Parameters
methodthe HTTP method name in all caps
paththe URI path without the leading "api"; if it does not begin with "latest" or "v#" (for a REST API version), then "/latest/" is prepended ot the path, meaning that the latest version of the REST API will be used
body_argsthe arguments to the call
Returns
the return value of the method
Note
to use a specific REST API version, make sure path begins with "/api"
See also

◆ callRestApiWithAuthentication()

static auto OMQ::UserApi::UserApi::callRestApiWithAuthentication ( string  user,
string  pass,
string  method,
string  path,
*hash< auto >  body_args 
)
static

calls a system REST API method with authentication information (username and password) and returns the result

Example:
int pid = UserApi::callRestApiWithAuthentication(user, pass, "PUT", "system?action=shutdown");
Parameters
userthe username to use for the call
passthe password to use for the call
methodthe HTTP method name in all caps
paththe URI path without the leading "api"; if it does not begin with "latest" or "v#" (for a REST API version), then "/latest/" is prepended ot the path, meaning that the latest version of the REST API will be used
body_argsthe arguments to the call
Returns
the return value of the method
Note
to use a specific REST API version, make sure path begins with "/api"
See also

◆ cancelOrder()

static hash<auto> OMQ::UserApi::UserApi::cancelOrder ( softint  wfiid)
static

cancel the given workflow order data instance

Parameters
wfiidthe workflow order instance ID to cancel
Returns
a hash with the following key:
  • workflow_status: the status of the workflow order

An exception will be thrown if the status is OMQ::StatInProgress

Exceptions
CANCEL-WORKFLOW-ERRORinvalid status, foreign session id, missing original status, uncancel operation already in progress
See also
cancel_order()

◆ clearSqlTableCache() [1/2]

static OMQ::UserApi::UserApi::clearSqlTableCache ( string  datasource,
*string  table_name 
)
static

clears all objects for given datasource from the cache (for example, if database objects have been updated in the dataserver)

Parameters
datasourcethe name of a Qorus datasource
table_namean optional table name to clear; if not present, then all objects in the given datasource are cleared
Example:
UserApi::clearSqlTableCache("omquser");

See

◆ clearSqlTableCache() [2/2]

static OMQ::UserApi::UserApi::clearSqlTableCache ( AbstractDatasource  datasource,
*string  table_name 
)
static

clears cached objects for given datasource (for example, if database objects have been updated in the dataserver)

Parameters
datasourcea DatasourcePool object for a Qorus datasource; note that if the Qore::SQL::DatasourcePool object cannot be matched back to a known Qorus datasource, an INVALID-DATASOURCE exception will be thrown
table_namean optional table name to clear; if not present, then all objects in the given datasource are cleared
Example:
UserApi::clearSqlTableCache(datasource_pool);
Exceptions
INVALID-DATASOURCEthis exception is thrown if the datasource argument cannot be matched to a known Qorus datasource
See also

◆ createOrder()

static softint OMQ::UserApi::UserApi::createOrder ( string  name,
*string  version,
hash  params,
string  status = StatReady 
)
static

creates a workflow order data instance in the database

Creates a workflow order data instance of the specified type with the data passed.

To ensure that a given workflow order is only created once for a given unique key value, make sure your workflow defines order keys, and use one of the following options to guarantee uniqueness of the order:

  • global_unique_key
  • workflow_specific_unique_key
  • workflow_unique_key
Parameters
namethe name of the workflow
versionthe version of the workflow; if this parameter is not passed, then the latest version of the workflow (determined by the latest created date for the workflow_instance entry) will be used
paramsThe hash passed must have at either a staticdata key or an external_order_instanceid key, valid keys:
  • dynamicdata: (optional hash) the initial dynamic data for the order
  • external_order_instanceid: (optional/required string) the external order instance ID for the workflow data; one of staticdata or external_order_instanceid must be provided
  • global_unique_key: (optional hash) a hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); keys are order key names and values are the string key values; if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys: (optional hash) a hash of order keys for the order
  • parent_workflow_instanceid: (optional int) a loosely-coupled workflow that will be marked as the parent of this workflow; if this key is not set, and this method is called from workflow code (even indirectly, by calling a service method that calls this method in the same thread as the call from workflow code), the new order will be loosely-coupled with the calling workflow order as the parent; to keep this from happening, set the value of this key to False
  • priority: the order priority (optional int, default DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • scheduled: (optional date) the earliest date and time the order can be processed; if this date is given as a future date/time value and a StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to StatScheduled instead of StatReady
  • sensitive_data: (optional hash) a hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values, and the hash values have the following keys:
    • aliases: (optional list of strings) zero or more string aliases for the sensitive data
    • data: (required hash) the sensitive data hash itself
    • meta: (optional hash) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
      • PURPOSE: free-form information about the purpose of the sensitive data
      • CATEGORIES: free-form information about the categories of sensitive data
      • RECIPIENTS: free-form information about the recipients or recipient catories of sensitive data
      • STORAGE: free-form information about the storage time or rules for sensitive data
  • staticdata: (optional/required hash) the initial static data for the order; one of staticdata or external_order_instanceid must be provided
  • tempdata: (optional hash) the initial temporary data for the order
  • workflow_specific_unique_key: (optional hash) a hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); keys are order key names and values are the string key values; if any of the keys given already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key: (optional hash) a hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); keys are order key names and values are the string key values; if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
statuscreate the workflow order data instance with this status; may be either:
  • StatReady which is the default value
  • StatBlocked meaning: do not process the order, wait for unblocking later
Returns
the workflow instance ID created
Exceptions
SUBMIT-ORDER-ERRORinvalid status value
ORDER-DATA-ERRORmissing either external_order_instanceid or staticdata, unknown workflow; invalid keys or sensitive data format
DUPLICATE-ORDER-KEYthe given unique key already exists in the defined scope, also sets arg with a workflow_instance_ids key with a list of all conflicting workflow instance IDs
WORKFLOW-KEY-ERRORinvalid workflow key given
Note
  • In the params argument above, either the staticdata or external_order_instanceid values must be provided; staticdata may be omitted if external_order_instanceid is provided and vice-versa
  • The global_unique_key, workflow_specific_unique_key, and workflow_unique_key options can be used to ensure that given workflow order data is only created once; note that any archiving schema is also searched when checking for duplicate keys. These options may be combined, but it's recommended to use no more than one key for uniqueness.
See also

◆ createRemoteOrder()

static softint OMQ::UserApi::UserApi::createRemoteOrder ( string  remote,
string  name,
*string  version,
hash  params,
string  status = StatReady,
bool  register_dependency = True 
)
static

creates a workflow order data instance in a remote Qorus instance

Creates a workflow order data instance of the specified type with the data passed in the specified remote Qorus instance.

To ensure that a given workflow order is only created once for a given unique key value, make sure your workflow defines order keys, and use one of the following options to guarantee uniqueness of the order:

  • global_unique_key
  • workflow_specific_unique_key
  • workflow_unique_key
Parameters
remotethe name of the remote Qorus connection
namethe name of the workflow
versionthe version of the workflow; if this parameter is not passed, then the latest version of the workflow (determined by the latest created date for the workflow_instance entry) will be used
paramsThe hash passed must have at either a staticdata key or an external_order_instanceid key, valid keys:
  • dynamicdata: (optional hash) the initial dynamic data for the order
  • external_order_instanceid: (optional/required string) the external order instance ID for the workflow data; one of staticdata or external_order_instanceid must be provided
  • global_unique_key: (optional hash) a hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); keys are order key names and values are the string key values; if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys: (optional hash) a hash of order keys for the order
  • parent_workflow_instanceid: (optional int) a loosely-coupled workflow that will be marked as the parent of this workflow; if this key is not set, and this method is called from workflow code (even indirectly, by calling a service method that calls this method in the same thread as the call from workflow code), the new order will be loosely-coupled with the calling workflow order as the parent; to keep this from happening, set the value of this key to False
  • priority: the order priority (optional int, default DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • scheduled: (optional date) the earliest date and time the order can be processed; if this date is given as a future date/time value and a StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to StatScheduled instead of StatReady
  • sensitive_data: (optional hash) a hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values, and the hash values have the following keys:
    • aliases: (optional list of strings) zero or more string aliases for the sensitive data
    • data: (required hash) the sensitive data hash itself
    • meta: (optional hash) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
      • PURPOSE: free-form information about the purpose of the sensitive data
      • CATEGORIES: free-form information about the categories of sensitive data
      • RECIPIENTS: free-form information about the recipients or recipient catories of sensitive data
      • STORAGE: free-form information about the storage time or rules for sensitive data
  • staticdata: (optional/required hash) the initial static data for the order; one of staticdata or external_order_instanceid must be provided
  • tempdata: (optional hash) the initial temporary data for the order
  • workflow_specific_unique_key: (optional hash) a hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); keys are order key names and values are the string key values; if any of the keys given already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key: (optional hash) a hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); keys are order key names and values are the string key values; if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
statuscreate the workflow order data instance with this status; may be either:
  • StatReady which is the default value
  • StatBlocked meaning: do not process the order, wait for unblocking later
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
the workflow instance ID created
Exceptions
GET-REMOTE-ERRORThe given connection is not known
SUBMIT-ORDER-ERRORinvalid status value
WORKFLOW-ERRORunknown or invalid workflow
ORDER-DATA-ERRORmissing either external_order_instanceid or staticdata, invalid keys or sensitive data format
DUPLICATE-ORDER-KEYthe given unique key already exists in the defined scope, also sets arg with a workflow_instance_ids key with a list of all conflicting workflow instance IDs
WORKFLOW-KEY-ERRORinvalid workflow key given
Note
  • In the params argument above, either the staticdata or external_order_instanceid values must be provided; staticdata may be omitted if external_order_instanceid is provided and vice-versa
  • The global_unique_key, workflow_specific_unique_key, and workflow_unique_key options can be used to ensure that given workflow order data is only created once; note that any archiving schema is also searched when checking for duplicate keys. These options may be combined, but it's recommended to use no more than one key for uniqueness.
See also

◆ deserializeQorusData()

static auto OMQ::UserApi::UserApi::deserializeQorusData ( string  data)
static

parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data

auto-detects XML-RPC or YAML decoding

Parameters
datathe string data to deserialize
Returns
the Qore data represented by the string arugment
See also

◆ execSynchronousWorkflow()

static hash<auto> OMQ::UserApi::UserApi::execSynchronousWorkflow ( string  name,
*string  version,
hash  sdata,
*hash  opts,
*hash  ddata,
softint  priority = DefaultOrderPriority,
*hash  orderkeys,
*softstring  external_order_instanceid,
*softint  parent_workflow_instanceid 
)
static

executes a workflow order synchronously and returns the final status and order ID in a hash

Parameters
namethe workflow name
versionthe workflow version (if NOTHING then the latest version of the workflow will be used)
sdatathe static data hash for the workflow order
optsthe options for the synchronous workflow execution instance
ddatathe optional initial dynamic data hash for the workflow order
prioritythe order priority for the order
orderkeysoptional order keys for the order
external_order_instanceidthe optional external order instanceid for the order
parent_workflow_instanceidan optional loosely-coupled workflow order ID that will be marked as the parent of this order; if this key is not set, and this method is called from workflow code (even indirectly, by calling a service method that calls this method in the same thread as the call from workflow code), the new order will be loosely-coupled with the calling workflow order as the parent; to keep this from happening, set the value of this key to False
Returns
a hash of workflow order information with the following keys:
See also
exec_synchronous_workflow()

◆ expandOneVariable()

static auto OMQ::UserApi::UserApi::expandOneVariable ( string  str,
string  var_context,
string  var_name,
*hash< auto >  local_context,
*bool  brackets 
)
static

expands one variable in a templated string

Parameters
strtemplated string to be expanded; see Config Item / Building Block Template Substitution Strings for more information on this parameter
var_contextcontext of the variable to be expanded (e.g. local, static, dynamic, keys,...)
var_namename of the variable to be expanded
local_contextlocal context supplied by the caller (plus user context info is added - see UserApi::getUserContextInfo() method)
bracketsif True then the variable was given in curly brackets
Returns
modified string with the specified variable already expanded
Exceptions
NOT-WF-CONTEXT-ERRORif WF specific context (e.g. static) variable is specified to be expanded
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
UNKNOWN-VALUE-ERRORif the variable doesn't have a value in the specified context
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
Note
the derived value is returned directly without recursive substitutions
See also
Config Item / Building Block Template Substitution Strings
Since
Qorus 4.0.3

◆ expandTemplatedValue()

static auto OMQ::UserApi::UserApi::expandTemplatedValue ( auto  value,
*hash< auto >  local_context 
)
static

expands all variables in a templated string

Parameters
valuetemplated string to be expanded; see Config Item / Building Block Template Substitution Strings for more information on this parameter
local_contextlocal context supplied by the caller (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
the value of the string as substituted with all variables expanded recursively until there are no more expansions to perform (or the derived value is not a string)
Exceptions
NOT-WF-CONTEXT-ERRORif WF specific context (e.g. static) variable is specified to be expanded
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
UNKNOWN-VALUE-ERRORif the variable doesn't have a value in the specified context
FORMAT-ERRORif the templated string doesn't have correct format (e.g. unescaped dollar sign that does not represent a variable)
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
See also
Config Item / Building Block Template Substitution Strings
Since
Qorus 4.0.3

◆ flushSlaEvents()

static OMQ::UserApi::UserApi::flushSlaEvents ( )
static

flushes all pending SLA events to disk and returns after the data has been committed

Example:
UserApi::flushSlaEvents();
See also
flush_sla_events()

◆ getActiveJobs()

static hash<auto> OMQ::UserApi::UserApi::getActiveJobs ( )
static

Returns information on all active jobs visible to the calling user.

If any active jobs are not accessible to the calling user, then they are filtered from the hash returned.

Returns
a hash is keyed by job name; the hash values are job information hashes with the following keys:
  • jobid: the metadata jobid of the job type
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • [job_instanceid]: the id of the job instance (will only have a value if the job is currently executing)
  • [last_executed]: the last executed date/time of the job (NOTHING if not yet executed)
  • [last_executed_job_instanceid]: the last executed instance id of the job
  • [expiry_date]: the expiry date of the job, if any; if this date is present, then the job will not run automatically after this date
  • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
  • [next]: the next trigger date/time; this key is only included if the job is active
  • active: this value is always True because this API only returns information about active jobs
See also
get_active_jobs()

◆ getBinaryFileFromLocation()

static binary OMQ::UserApi::UserApi::getBinaryFileFromLocation ( string  location)
static

returns binary data for the given file location

Parameters
locationthe location of the file data (ex: "resource://service-name:path/to/resource"); supported schemes are as follows:
  • file://file_location
    • file_location: gives the file location; environment variable substitution is performed
    • ex: file://$OMQ_DIR/user/file.txt
  • resource://[[remote:]service:]resource_path Note that service: is not required when this method is called from a service itself; in this case the given resource will be retrieved from the current service, however in all other cases at latest service: is required or a LOCATION-ERROR exception will be thrown
Returns
the resource data as a binary value
Exceptions
LOCATION-ERRORthe location string cannotbe parsed; unknown location scheme; invalid location option
Since
Qorus 4.0.3

◆ getConfigItemValue()

static auto OMQ::UserApi::UserApi::getConfigItemValue ( string  cfg_item,
*hash< auto >  local_context 
)
static

returns config item value in the current user context

Parameters
cfg_itemname of the config item
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid in the current context
Returns
value for the given config item in the current CONTEXT
Note
the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution

◆ getDatasourceDedicated()

static Qore::SQL::Datasource OMQ::UserApi::UserApi::getDatasourceDedicated ( string  name,
bool  register_dependency = True 
)
static

returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions

Parameters
namethe name of the datasource
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
a new, dedicated Datasource object, suitable for transaction management for long-running transactions
Exceptions
DATASOURCE-ERRORThe given connection is not known or is a system datasource
See also

◆ getDatasourceInfo()

static hash<auto> OMQ::UserApi::UserApi::getDatasourceInfo ( string  name)
static

returns a hash of information for the given datasource, if known, otherwise throws an exception

Parameters
namethe name of the datasource
Returns
a hash of information for the given datasource, if known, otherwise throws an exception; the following keys are returned in the hash:
  • name (string): the name of the datasource connection (corresponding to the argument name)
  • type (string): datasource constant
  • url (string): a connection string
  • url_hash (hash): parsed connection string and options
    • type (string): driver name
    • user (string): the username for the datasource connection, if any
    • pass (string): the password for the datasource connection, if any
    • charset (string): the DB-specific character encoding for the datasource connection
    • db (string): The database name of the datasource connection
    • options (hash): an optional hash of options for the DBI driver for this datasource connection; also "min" and "max" for the DatasourcePool minimum and maximum options
  • locked (bool): a flag indicating if the datasource is locked or not (the system datasource "omq" is locked)
  • up (bool): a flag indicating if monitoring has discovered if the datasource is up or not
  • desc (string): a string description of the datasource
  • monitor (bool): a flag indicating if the datasource is monitored or not
  • status (string): "OK" if the datasource is up or an error string if the datasource is down; set by monitoring
  • last_check (date/time): the date and time of the last monitoring check
  • shared_pool (string): a string giving the pool state (only present if a pool has been initialized on the datasource)
  • deps (list): a list of hashes giving interface objects that depend on the connection; each entry is a hash with the following keys:
    • type: "WORKFLOW", "SERVICE", or "JOB"
    • workflowid: for workflows, gives the workflow ID
    • serviceid: for services, gives the service ID
    • jobid: for jobs, gives the job ID
    • name: the name of the workflow, service, or job
    • version: the version of the workflow, service, or job
    • desc: a string description of the object
Exceptions
DATASOURCE-ERRORunknown datasource
See also
get_datasource_info()

◆ getDatasourcePool()

static AbstractDatasource OMQ::UserApi::UserApi::getDatasourcePool ( string  name,
bool  register_dependency = True 
)
static

returns a DatasourcePool object for the given datasource name

Parameters
namethe name of the datasource
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
a DatasourcePool object
Exceptions
DATASOURCE-ERRORunknown or system datasource
See also

◆ getGlobalConfigItemValue()

static auto OMQ::UserApi::UserApi::getGlobalConfigItemValue ( string  item,
*hash< auto >  local_context 
)
static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters
itemthe name of the configuration item to retrieve the value
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
the value of the given configuration item on global level
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
Since
Qorus 4.0.3
See also
getGlobalConfigItemValueWithDefault()

◆ getGlobalConfigItemValueWithDefault()

static auto OMQ::UserApi::UserApi::getGlobalConfigItemValueWithDefault ( string  item,
auto  default_value,
*hash< auto >  local_context 
)
static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters
itemthe name of the configuration item to retrieve the value
default_valuethe value to be returned if the value is not set
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
the value of the given global configuration item or default_value, if no value is set at the global level for the given configuration item
Note
Since
Qorus 4.0.3
See also
getGlobalConfigItemValue()

◆ getHashDotValue()

static auto OMQ::UserApi::UserApi::getHashDotValue ( *hash< auto >  var_data,
string  var_name 
)
static

returns the value of the given key from the given hash, respects dot notation in the key name

Parameters
var_datathe hash to search
var_namethe key value to use; respects dot notation
Returns
the value referenced or NOTHING if not present
Since
Qorus 4.0.3

◆ getInputData() [1/2]

static auto OMQ::UserApi::UserApi::getInputData ( string  field_name,
*hash< auto >  local_context,
*hash< auto >  input_data_cfg 
)
static

returns specified input data field's value

Example:
hash<auto> account_info_hash = {
"accountIdNumber": "123456ABC";
};
# this will be assigned "123456ABC";
string account_id = UserApi::getInputData("account_id", account_info_hash, {"account_id": "$local:accountIdNumber"});
Parameters
field_namename of the field that should be returned; identifies a key in input_data_cfg
local_contextthe caller can supply its "$local:" context for template variables (plus user context info is added - see UserApi::getUserContextInfo()); hash values are subject to recursive template variable expansion
input_data_cfginput data configuration; if not provided, the default location for the input data config is retrieved from current configuration item "input_data"; field_name must be present in this hash; string values of the key referenced with field_name in this hash are subject to recursive template variable expansion, and the resulting value is returned; non-string values are returned as-is
Returns
the value of the key given by field_name in the input_data_cfg hash is subject to recursive template variable expansion and returned; template variable expansion is performed if the hash value is a string, if the value is any other data type, it is returned as-is
Exceptions
NOT-WF-CONTEXT-ERRORif WF specific context (e.g. static) variable is specified to be expanded
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
UNKNOWN-VALUE-ERRORif the variable doesn't have a value in the specified context
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
INVALID-ARGUMENTif the field_name is not present in input data
See also
Config Item / Building Block Template Substitution Strings for information on template variable expansion
Since
Qorus 4.0.3

◆ getInputData() [2/2]

static hash<auto> OMQ::UserApi::UserApi::getInputData ( *hash< auto >  input_data_cfg,
*hash< auto >  local_context 
)
static

returns all input data

Example:
hash<auto> account_info_hash = {
"accountIdNumber": "123456ABC";
};
# will be assigned {"account_id": "123456ABC"}
hash<auto> input_info = UserApi::getInputData({"account_id": "$local:accountIdNumber"}, account_info_hash);
Parameters
local_contextthe caller can supply its "$local:" context for template variables (plus user context info is added - see UserApi::getUserContextInfo()); hash values are subject to recursive template variable expansion
input_data_cfginput data configuration; if not provided, the default location for the input data config is retrieved from configuration item "input_data"
Returns
the entire input data hash with all string hash values subject to recursive template variable expansion; input data hash values that are not strings are returned as-is
Exceptions
NOT-WF-CONTEXT-ERRORif WF specific context (e.g. static) variable is specified to be expanded
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
UNKNOWN-VALUE-ERRORif the variable doesn't have a value in the specified context
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
Since
Qorus 4.0.3

◆ getMapper()

static Mapper::Mapper OMQ::UserApi::UserApi::getMapper ( string  name,
*hash< auto >  rtopts 
)
static

returns the given mapper if registered for the current interface

Example:
Mapper m = UserApi::getMapper("my_mapper");
Parameters
namethe name of the mapper
rtoptsany runtime options accepted by the mapper
Exceptions
MAPPER-ERRORthe given mapper is unknown or not registered to the current interface
See also

◆ getMapperIterator()

static Qore::AbstractIterator OMQ::UserApi::UserApi::getMapperIterator ( string  name,
Qore::AbstractIterator  input,
*hash< auto >  rtopts 
)
static

returns an iterator for the named mapper using the iterator argument for input

Example:
AbstractIterator i = UserApi::getMapperIterator("my_mapper", input);
Parameters
namethe name of the mapper
inputan iterator providing the input for the mapper for the iterator returned; the input iterator must iterate hashes (as returned by the Qore::AbstractIterator::getValue() method)
rtoptsany runtime options accepted by the mapper
Returns
the AbstractIterator object corresponding to the arguments; the Qore::AbstractIterator::getValue() method will return a hash of the current input mapped to the output data structure
Exceptions
MAPPER-ERRORunknown mapper or not registered to the current interface
See also

◆ getNextSequenceValue() [1/2]

static softint OMQ::UserApi::UserApi::getNextSequenceValue ( AbstractDatasource  ds,
string  name 
)
static

returns the next sequence value for the given datasource and sequence

Example:
int val = UserApi::getNextSequenceValue(ds, seqnem);
Parameters
dsthe datasource to retrieve the sequence from
namethe name of the sequence
Returns
the next value of the sequence

◆ getNextSequenceValue() [2/2]

static softint OMQ::UserApi::UserApi::getNextSequenceValue ( string  ds,
string  name 
)
static

returns the next sequence value for the given datasource and sequence

Example:
int val = UserApi::getNextSequenceValue(ds, seqnem);
Parameters
dsthe datasource name to retrieve the sequence from; a pool corresponding to the datasource will be used to retrieve the sequence
namethe name of the sequence
Returns
the next value of the sequence

◆ getOption()

static auto OMQ::UserApi::UserApi::getOption ( )
static

Returns the value of the named workflow, service, or job option or options.

If the option is not set on the workflow, service, or job level (depending on the calling context) and it is a valid system option, then the value of the system option will be returned.

Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if called from a workflow and no arguments are passed to the method all workflow-level options are returned as a hash
Note
When called from workflow code, invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getOptionArgs()

static auto OMQ::UserApi::UserApi::getOptionArgs ( *softlist< string args)
static

Returns the value of the named workflow, service, or job option or options.

If the option is not set on the workflow, service, or job level (depending on the calling context) and it is a valid system option, then the value of the system option will be returned.

Parameters
argsthe list of options to return
Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if called from a workflow and no arguments are passed to the method all workflow-level options are returned as a hash
Note
When called from workflow code, invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getQorusOptionInfo()

static hash<auto> OMQ::UserApi::UserApi::getQorusOptionInfo ( )
static

returns a hash giving information about system options

See also
get_qorus_option_info()

◆ getQorusOptionInfoArgs()

static hash<auto> OMQ::UserApi::UserApi::getQorusOptionInfoArgs ( *list< auto >  args)
static

returns a hash giving information about system options

See also
get_qorus_option_info_args()

◆ getQorusOptions()

static auto OMQ::UserApi::UserApi::getQorusOptions ( )
static

returns the value of the given system option or options

See also
get_qorus_options()

◆ getQorusOptionsArgs()

static auto OMQ::UserApi::UserApi::getQorusOptionsArgs ( softlist  args)
static

returns the value of the given system option or options

See also
get_qorus_options_args()

◆ getRemoteRestConnection()

static QorusSystemRestHelper OMQ::UserApi::UserApi::getRemoteRestConnection ( string  name,
bool  connect = True,
bool  register_dependency = True 
)
static

Returns a new QorusSystemRestHelper object corresponding to a defined Qorus remote connection.

Parameters
namethe name of the remote connection
connectif False an unconnected object will be returned, otherwise the object is already connected
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
a new QorusSystemRestHelper object
Exceptions
GET-REMOTE-ERRORThe given connection is not known
See also
get_remote_rest_connection

◆ getRemoteRpcConnection()

static QorusSystemAPIHelper OMQ::UserApi::UserApi::getRemoteRpcConnection ( string  name,
bool  connect = True,
bool  register_dependency = True 
)
static

Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus remote connection.

Parameters
namethe name of the remote connection
connectif False an unconnected object will be returned, otherwise the object is already connected
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
a new QorusSystemAPIHelper object
Exceptions
GET-REMOTE-ERRORThe given connection is not known
See also
get_remote_rpc_connection()

◆ getRunningWorkflowInfo()

static hash OMQ::UserApi::UserApi::getRunningWorkflowInfo ( softint  id)
static

returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not

returns an empty hash if the workflow execution ID is not currently valid

Parameters
idworkflow execution instance id
Returns
a hash of the workflow execution instance info if the ID is valid or an empty hash if not; if valid, the hash will have the following keys:
  • name: the name of the workflow
  • version: version of the workflow
  • workflowid: the workflowid of the workflow
  • executionID: the workflow execution instance id (same as the argument)
  • mode: WM_Normal or WM_Recovery
  • sync: True if the execution instance is synchronous, False if not
  • status: WISInitializing, WISRunning, WISWaiting, WISStopping
  • iterations: number of segment iterations performed so far
  • totalSegments: number of segments executed
  • errors: total number of errors encountered
  • warnings: total number of warnings raised
  • starttime: date/time the execution instance was started
  • options: options set on the workflow execution instance
  • logfile: log file name
  • remote: True if the workflow is running as a remote qwf process, False if not
See also

◆ getRunningWorkflowList()

static list OMQ::UserApi::UserApi::getRunningWorkflowList ( *string  name,
*string  ver 
)
static

returns a list of hashes giving information about the currently-running workflow execution instances

Parameters
nameoptional workflow name for filtering the result list
veroptional workflow version for filtering the result list (only used if name also passed)
Returns
a list of hashes giving information about the currently-running workflow execution instances; if no matching workflow execution instances are running, then an empty list is returned; otherwise each list element is a hash with the following keys:
  • executionID: the workflow execution instance id
  • name: the name of the workflow
  • version: version of the workflow
  • workflowid: the workflowid of the workflow
  • mode: WM_Normal or WM_Recovery
  • sync: True if the execution instance is synchronous, False if not
  • status: WISInitializing, WISRunning, WISWaiting, WISStopping
  • iterations: number of segment iterations performed so far
  • totalSegments: number of segments executed
  • errors: total number of errors encountered
  • warnings: total number of warnings raised
  • starttime: date/time the execution instance was started
  • options: options set on the workflow execution instance
  • logfile: log file name
  • remote: True if the workflow is running as a remote qwf process, False if not
See also

◆ getServiceInfo()

static *hash OMQ::UserApi::UserApi::getServiceInfo ( string  type,
string  name 
)
static

returns information about the given service (if it's currently loaded)

to get information about services whether they are loaded or not, call:

omqservice.system.omqmap.lookupserviceinfo(<type>, <name>)
Parameters
typethe type of service (either "system" or "user"; case is ignored)
namethe name of the system service to query
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • patch: the patch string for the service
  • desc: description of the service
  • author: the author of the service
  • serviceid: service ID
  • parse_options: parse options for the service
  • status: SSRunning or SSLoaded
  • log: path to the service log file
  • active_calls: number of active service calls and persistent connection handlers currently in progress
  • waiting_threads: number of threads waiting on the service (for a service reset or unload action)
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • manual_autostart: True of False the autostart value has been manually set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
  • resources: list of service resources
  • resource_files: list of service file resources
  • options: service options
  • groups: interface groups that the service belongs to
  • alerts: any alerts raised against the service
See also
get_service_info()

◆ getSessionId()

static int OMQ::UserApi::UserApi::getSessionId ( )
static

returns the current Qorus application session ID

Returns
the current Qorus application session ID
See also

◆ getSqlCacheInfo()

static hash<auto> OMQ::UserApi::UserApi::getSqlCacheInfo ( )
static

get information about cached object

Returns
hash the whole sql cache

Resulting hash (keys are datasource names) of hashes (keys are cache types) of hashes (keys are names of individual cached objects) provides the information about given cached objects as a value. This information has the form of hash with the following keys:

  • count - how many times it was used
  • created - datetime of the first call (when the cache was created)
  • object - stored object that is cached
Example:
hash cache = UserApi::getSqlCacheInfo();
hash cache_for_my_datasource = cache.my_datasource;
hash table_cache_for_my_datasource = cache_for_my_datasource.tables;
bool is_mytable_cached = exists table_cache_for_my_datasource.my_table;
date date_when_mytable_was_cached = table_cache_for_my_datasource.my_table.created;
See also

◆ getSqlTable() [1/2]

static SqlUtil::AbstractTable OMQ::UserApi::UserApi::getSqlTable ( string  datasource,
string  table_name,
bool  register_dependency = True 
)
static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Example:
SqlUtil::AbstractTable t = UserApi::getSqlTable("pgsql:user/password@db", "my_table");
Parameters
datasourcea Qorus datasource name
table_namethe name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
an SqlUtil::AbstractTable object corresponding to the parameters
Exceptions
INVALID-DATASOURCEthis exception is thrown if the datasource argument cannot be matched to a known datasource
Note
  • other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
  • you need to call clear_sql_table_cache() any time the table structure has changed
See also
Since
Qorus 4.0.3 added the register_dependency parameter

◆ getSqlTable() [2/2]

static SqlUtil::AbstractTable OMQ::UserApi::UserApi::getSqlTable ( AbstractDatasource  datasource,
string  table_name,
bool  register_dependency = True 
)
static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Parameters
datasourcea DatasourcePool object for a Qorus datasource; note that if the Qore::SQL::DatasourcePool object cannot be matched back to a known Qorus datasource, an INVALID-DATASOURCE exception will be thrown
table_namethe name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
an SqlUtil::AbstractTable object corresponding to the parameters
Exceptions
INVALID-DATASOURCEthis exception is thrown if the datasource argument cannot be matched to a known Qorus datasource
Note
  • INVALID-DATASOURCE exceptions can be thrown with a valid Qorus datasource if the given datasource has been reset since it was acquired
  • other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
  • you need to call clear_sql_table_cache() any time the table structure has changed
Example:
SqlUtil::AbstractTable t = UserApi::getSqlTable(datasource_pool, "my_table");
See also
Since
Qorus 4.0.3 added the register_dependency parameter

◆ getSystemInfo()

static hash OMQ::UserApi::UserApi::getSystemInfo ( )
static

returns a hash of system info

Returns
a hash of system info with the following keys:
  • instance-key: value of the system option by the same name
  • session-id: the session ID for the current Qorus application session
  • omq-version: the version string for the Qorus server
  • omq-version-code: a numeric code of the Qorus server version, where
    major = (x / 10000), minor = (x / 100) % 100, = x % 100
    this value is suitable for comparisons (ex: for Qorus 2.6.0, omq-version-code = 20600)
  • qore-version: the version string for the qore build used
  • datamodel-version: the datamodel version required by this version of Qorus
  • omq-schema: the datasource string for the system schema (without the password)
  • omquser-schema: the datasource string for the user schema (without the password)
  • starttime: the date and time when the instance was started
  • hostname: the hostname of the machine where the Qorus server is running
  • pid: the PID of the Qorus server process
  • threads: number of threads currently active
  • schema-properties: a hash of schema properties with the following keys:
  • omq-schema-version
  • omq-schema-compatibility
  • omq-load-schema-compatibility
  • logfile: the path for the system log file
See also
get_system_info()

◆ getSystemServiceInfo()

static *hash<auto> OMQ::UserApi::UserApi::getSystemServiceInfo ( string  name)
static

returns information about the given system service (if it's currently loaded)

to get information about system services whether they are loaded or not, call:

omqservice.system.omqmap.lookupserviceinfo("system", <name>)
Parameters
namethe name of the system service to query
Returns
a hash of user information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: "system"
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: SSRunning or SSLoaded
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
See also
get_system_service_info()

◆ getTextFileFromLocation()

static string OMQ::UserApi::UserApi::getTextFileFromLocation ( string  location)
static

returns string data for the given file location

Parameters
locationthe location of the file data (ex: "resource://service-name:path/to/resource"); supported schemes are as follows:
  • file://file_location
    • file_location: gives the file location; environment variable substitution is performed
    • ex: file://$OMQ_DIR/user/file.txt
  • resource://[[remote:]service:]resource_path Note that service: is not required when this method is called from a service itself; in this case the given resource will be retrieved from the current service, however in all other cases at latest service: is required or a LOCATION-ERROR exception will be thrown
Returns
the resource data as a string
Exceptions
LOCATION-ERRORthe location string cannotbe parsed; unknown location scheme; invalid location option
Since
Qorus 4.0.3

◆ getUserConnection()

static object OMQ::UserApi::UserApi::getUserConnection ( string  name,
bool  connect = True,
bool  register_dependency = True,
*hash< auto >  rtopts 
)
static

Returns an object corresponding to a defined user connection.

Parameters
namethe name of the connection
connectif False an unconnected object will be returned, otherwise the object is already connected
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
rtoptsany runtime options accepted by the connection
Returns
the object representing the connection
Exceptions
CONNECTION-ERRORThe given connection is not known
See also
get_user_connection()

◆ getUserContextInfo()

static *hash<auto> OMQ::UserApi::UserApi::getUserContextInfo ( )
static

returns a hash for the current user context

Example:
*hash<auto> h = UserApi::getUserContextInfo();
Returns
a hash describing the current user context or NOTHING if called outside a workflow, service, or job; hash keys are as follows:
  • when called in a service:
    • "type": "service"
    • "servicetype": the type of service ("user" or "system")
    • "name": the name of the service
    • "version": the version of the service
    • "id": the service id
  • when called in a job:
    • "type": "job"
    • "name": the name of the job
    • "version": the version of the job
    • "id": the job id
    • "job_instanceid": the job_instanceid of the current job instance
  • when called in a workflow:
    • "type": "workflow"
    • "name": the name of the workflow
    • "version": the version of the workflow
    • "id": the workflow id
    • "workflow_instanceid": the workflow_instanceid of the current workflow instance (if available)
    • "stepname": the name of the current step (if available)
    • "stepversion": the version of the current step (if available)
    • "stepid": the id of the current step (if available)
    • "ind": the name of the current step index (if available)
    • "execid": the execution ID of the current workflow execution instance (if available)
See also
get_user_context_info()

◆ getUserServiceInfo()

static *hash<auto> OMQ::UserApi::UserApi::getUserServiceInfo ( string  name)
static

returns information about the given user service (if it's currently loaded)

to get information about user services whether they are loaded or not, call:

omqservice.system.omqmap.lookupserviceinfo("user", <name>)
Parameters
namethe name of the user service to query
Returns
a hash of user information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: "user"
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: SSRunning or SSLoaded
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
See also
get_user_service_info()

◆ getValueMap()

static auto OMQ::UserApi::UserApi::getValueMap ( string  mapname,
string  key 
)
static

Gets a lookup value from the value map by a key; the value map must be registered to the current interface.

Parameters
mapnamename of the value map
keya key name
Returns
the value assigned to the key
Exceptions
VALUE-MAP-ERRORthe given value map is unknown or not registered to the current interface
See also

◆ getValueMaps()

static list<auto> OMQ::UserApi::UserApi::getValueMaps ( )
static

Gets all value maps valid for the current interface.

Returns
a list of hashes describing available value maps; keys are value map names; values are hashes with the following keys:
  • "id": the internal ID of the value map
  • "name": the name of the value map
  • "description": a string describing the value map
  • "author": the author tag
  • "throws_exception": a tag that controls the behavior when an unknown mapping is referenced (Value Map Error Handling and Missing Data)
  • "valuetype": the type of values in the map
  • "created": the created time stamp
  • "modified": the last modified time stamp
See also

◆ isSingleTemplatedString()

static bool OMQ::UserApi::UserApi::isSingleTemplatedString ( auto  value)
static

checks if the given value is a templated string with only one expandable variable

Parameters
valueto check
Returns
return True if value is a templated string with only one expandable variable otherwise False
Since
Qorus 4.0.3

◆ logArgsDebug()

static OMQ::UserApi::UserApi::logArgsDebug ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logDebug()

◆ logArgsError()

static OMQ::UserApi::UserApi::logArgsError ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logError()

◆ logArgsFatal()

static OMQ::UserApi::UserApi::logArgsFatal ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logFatal()

◆ logArgsInfo()

static OMQ::UserApi::UserApi::logArgsInfo ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logInfo()

◆ logArgsTrace()

static OMQ::UserApi::UserApi::logArgsTrace ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logTrace()

◆ logArgsWarn()

static OMQ::UserApi::UserApi::logArgsWarn ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logWarn()

◆ logDebug()

static OMQ::UserApi::UserApi::logDebug ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsDebug()

◆ logError()

static OMQ::UserApi::UserApi::logError ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsError()

◆ logFatal()

static OMQ::UserApi::UserApi::logFatal ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsFatal()

◆ logInfo()

static OMQ::UserApi::UserApi::logInfo ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsWarn()

◆ logTrace()

static OMQ::UserApi::UserApi::logTrace ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logTrace()

◆ logWarn()

static OMQ::UserApi::UserApi::logWarn ( softstring  msg)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsWarn()

◆ postSlaEventError()

static bool OMQ::UserApi::UserApi::postSlaEventError ( string  sla,
number  value,
string  err,
string  desc 
)
static

posts an unsuccessful SLA event for SLA monitoring and performance tracking

Example:
UserApi::postSlaEventError(sla, value, ex.err, ex.desc);
Parameters
slathe SLA name
valuethe SLA performance value
errthe error code for the SLA event error
descthe error description for the SLA event error
Returns
True if the event was posted, False if not (because the SLA does not exist)
See also
post_sla_event_error()

◆ postSlaEventSuccess()

static bool OMQ::UserApi::UserApi::postSlaEventSuccess ( string  sla,
number  value 
)
static

posts a successful SLA event for SLA monitoring and performance tracking

Example:
UserApi::postSlaEventSuccess(sla, value);
Parameters
slathe SLA name
valuethe SLA performance value
Returns
True if the event was posted, False if not (because the SLA does not exist)
See also
post_sla_event_success()

◆ postSyncEvent()

static bool OMQ::UserApi::UserApi::postSyncEvent ( string  eventtype,
string  eventkey 
)
static

posts a workflow synchronization event given the event type name and the unique event key

Example:
UserApi::postSyncEvent(type, key);
Parameters
eventtypethe event type name
eventkeythe event key in the event type queue to post
Returns
True if the event was posted for the first time, False if the event had already been posted beforehand
Exceptions
UNKNOWN-EVENTunknown event type name
See also

◆ postUserEvent()

static int OMQ::UserApi::UserApi::postUserEvent ( string  severity,
auto  info 
)
static

posts an application event of class QE_CLASS_USER

Parameters
severitysee Error Severity Codes for possible values
infothe user-defined information for the event
Exceptions
POST-USER-EVENT-ERRORinvalid severity value
See also
post_user_event()

◆ propGet() [1/3]

static hash<auto> OMQ::UserApi::UserApi::propGet ( )
static

returns a hash of all system properties in all domains

Example:
hash<auto> h = UserApi::propGet();
Returns
a hash of all system properties in all domains; the top-level keys are domain keys which have as values hashes with all key-value pairs set in the domain
See also

◆ propGet() [2/3]

static *hash<auto> OMQ::UserApi::UserApi::propGet ( string  domain)
static

returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

Example:
*hash<auto> h = UserApi::propGet(domain);
Returns
a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist
See also

◆ propGet() [3/3]

static auto OMQ::UserApi::UserApi::propGet ( string  domain,
string  key 
)
static

returns the value of the given system property key in the given domain or NOTHING if the system property does not exist

Example:
auto val = UserApi::propGet(domain, key);
Returns
the value of the given system property key in the given domain
See also

◆ propUpdate() [1/2]

static string OMQ::UserApi::UserApi::propUpdate ( string  domain,
softstring  key,
auto  value 
)
static

changes (inserts, updates, or deletes) the value of a single system property

Example:
UserApi::propUpdate(domain, key, val);

Updates the value of the property in the domain passed. If the property does not exist, then it is created. If the value is NOTHING (i.e. if no value is supplied) then the property will be deleted. Changes are committed to the database and the internal cache before the method call returns. No changes may be made in the system "omq" domain.

Parameters
domainthe domain of the property to set
keythe key to set
valuethe value to set in the property domain; if no value is passed here, and the property exists, it will be deleted
Returns
the action code, "INSERT", "UPDATE", "DELETE", "IGNORED" (if a non-existent key should be deleted)
Exceptions
PARAMETER-ERRORif the domain or key arguments are empty strings
PROP-ERRORserialized value exceeds 240 characters (column limit)
UPDATE-ERRORchanges attempted in the "omq" domain
See also

◆ propUpdate() [2/2]

static hash<auto> OMQ::UserApi::UserApi::propUpdate ( hash< auto >  h)
static

changes (inserts, updates, or deletes) the value of one or more system properties according to a hash argument

Example:
UserApi::propUpdate(h);

Updates the values of the properties in the domain corresponding to the top level keys of the hash passed and the keys corresponding to the second-level keys in the hash according to the rules for prop_update(domain, key, value) method.

The method returns a hash with "INSERT", "UPDATE", "DELETE" and "IGNORED" keys having integer values corresponding to the number of operations performed (deleting a non-existent key or domain causes a "IGNORED" value to be returned).

All changes are made atomically in a single transaction.

Parameters
hin the format domain.key.value for updating, inserting, or deleting
Returns
a hash of action codes as keys, with the values of each key being the number of actions of that type executed
Exceptions
PROP-ERRORserialized value exceeds 240 characters (column limit)
UPDATE-ERRORchanges attempted in the "omq" domain
See also

◆ qorusGetLocalUrl()

static string OMQ::UserApi::UserApi::qorusGetLocalUrl ( *string  username,
*string  password 
)
static

returns a string giving the local system URL

Parameters
usernamean optional username for the new connection
passwordan optional password for the new connection
Returns
a string giving the local system URL
Note
the username and password arguments are only used if both are given
See also
qorus_get_local_url()

◆ raiseTransientAlert()

static OMQ::UserApi::UserApi::raiseTransientAlert ( string  alert,
string  reason,
*hash< auto >  info 
)
static

raises a transient system alert from a workflow, service, or job

Parameters
alertthe name of the alert (ex: "DATA-SIZE-EXCEEDED")
reasonthe reason or verbose description of the alert
infooptional key / value details for the alert
See also
raise_transient_alert()

◆ restartTransaction()

static *string OMQ::UserApi::UserApi::restartTransaction ( string  driver,
hash< auto >  ex 
)
static

returns a string error message if any exception in the chain passed was caused by a recoverable DB error, otherwise returns NOTHING

Parameters
driverthe database driver name, which must be a driver supported by the Qorus system schema, currently one of "oracle", "pgsql", or "mysql", otherwise an UNSUPPORTED-DRIVER exception is thrown
exthe exception hash
Returns
a string error message if any exception in the chain passed was caused by a recoverable DB error, otherwise returns NOTHING
Exceptions
UNSUPPORTED-DRIVERonly "oracle", "pgsql", and "mysql" are currently supported

◆ runtimeProperties()

static hash OMQ::UserApi::UserApi::runtimeProperties ( )
static

returns Qorus runtime properties as a hash

Returns
Qorus runtime properties as a hash; if no properties are set, returns an empty hash
See also
runtime_properties()

◆ serializeQorusData()

static string OMQ::UserApi::UserApi::serializeQorusData ( auto  d)
static

returns a string giving the default serialization of the given data structure for storage in Qorus

the default serialization is currently YAML

Parameters
dthe data to serialize
Returns
a YAML string representing the given data structure for storage in Qorus, in case the given data is NOTHING an empty string is returned
See also

◆ serializeQorusDataWithNothing()

static string OMQ::UserApi::UserApi::serializeQorusDataWithNothing ( auto  d)
static

returns a string giving the default serialization of the given data structure for storage in Qorus

the default serialization is currently YAML

Parameters
dthe data to serialize
Returns
a YAML string representing the given data structure for storage in Qorus
See also

◆ setOption()

static OMQ::UserApi::UserApi::setOption ( hash< auto >  hash)
static

Changes option values on a workflow, service, or job.

if called from workflow code, and the workflow has defined workflow options and an invalid option is passed to the method, an exception will be raised; however all other valid options in the hash will be set before the exception is raised

Parameters
hasha hash of option-value pairs
Exceptions
WORKFLOW-OPTION-ERRORinvalid option name
See also
set_option()

◆ sleep()

static int OMQ::UserApi::UserApi::sleep ( softint  arg)
static

puts the current thread to sleep for a certain number of seconds

If the job, workflow execution instance, or service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or omqusleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of seconds to sleep
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ unblockOrder()

static hash<auto> OMQ::UserApi::UserApi::unblockOrder ( softint  wfiid,
*hash< auto >  tempdata,
*hash< auto >  orderkeys 
)
static

unblocks the given workflow order data instance

Parameters
wfiidthe workflow order instance ID to unblock
tempdataoptional workflow order tempdata to pass to the workflow order (will only be used if the order is immediately cached as a part of the unblock_order() call)
orderkeysoptional workflow order data keys
Returns
a hash with the following key:
  • workflow_status: the status of the workflow order
Exceptions
BLOCK-WORKFLOW-ERRORinvalid status, foreign session id, missing original status, uncancel operation already in progress
See also
unblock_order()

◆ uncancelOrder()

static hash<auto> OMQ::UserApi::UserApi::uncancelOrder ( softint  wfiid,
*hash< auto >  tempdata 
)
static

uncancels the given workflow order data instance

Parameters
wfiidthe workflow order instance ID to uncancel
tempdatatemporary data to provide when uncanceling the order
Returns
a hash with the following key:
  • workflow_status: the status of the workflow order
Exceptions
CANCEL-WORKFLOW-ERRORinvalid status, foreign session id, missing original status, uncancel operation already in progress
See also
uncancel_order()

◆ updateHashDotValue()

static *hash<auto> OMQ::UserApi::UserApi::updateHashDotValue ( *hash< auto >  var_data,
string  var_name,
auto  value 
)
static

updates the given hash with a key in dot notation with the given value

Example:
# will assign {"account": {"id": "123456ABC"}}
hash<auto> updated_hash = UserApi::updateHashDotValue({}, "account.id", "123456ABC");
Parameters
var_datathe hash to update
var_namethe key name to update in dot notation
valuethe value to set
Returns
the updated hash
Since
Qorus 4.0.3

◆ updateOutputData() [1/2]

static OMQ::UserApi::UserApi::updateOutputData ( string  field_name,
auto  output_data,
*hash< auto >  output_data_cfg 
)
static

updates specified output data field's value

Example:
# write the account ID to the account -> id field in dynamic data
UserApi::updateOutputData("account_id", account_id, {"account_id": "$dynamic:account.id"});
Parameters
field_namename of the field that should be updated; identifies a key in output_data_cfg that provides the location for writing the output data
output_datathe value to write in the location determined by the field_name key in output_data_cfg
output_data_cfga hash of values giving output data locations; if not provided, the default location for the output data config is retrieved from configuration item "output_data"; field_name must be present in this hash; string values of the key referenced with field_name in this hash provide the location to write output_data and are not subject to template variable expansion
Exceptions
UNSUPPORTED-CONTEXT-ERRORif output data configuration specifies an unsupported context
OUTPUT-CONFIG-ERRORfield_name is not present in output_data_cfg
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
SET-ORDER-KEYS-ERRORmissing value for order key
INVALID-WORKFLOW-KEYworkflow key not valid for the current workflow
DUPLICATE-KEY-VALUEduplicate value provided for order key
Since
Qorus 4.0.3

◆ updateOutputData() [2/2]

static OMQ::UserApi::UserApi::updateOutputData ( hash< auto >  all_output_data,
hash< auto >  output_data_cfg = UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY) 
)
static

updates all output data

Example:
# write the account ID to the account -> id field in dynamic data
UserApi::updateOutputData({"account_id": account_id}, {"account_id": "$dynamic:account.id"});
Parameters
all_output_dataa hash giving output data; keys in this hash must match a corresponding key in output_data_cfg which will provide the location for writing the value, values in this hash will be written to the locations provided in output_data_cfg
output_data_cfga hash of values giving output data locations; if not provided, the default location for the output data config is retrieved from configuration item "output_data"; all keys in all_output_data must also be present in this hash; string values of referenced keys in this hash provide the location to write the values of the all_output_data hash; these values are not subject to template variable expansion

For a list of supported output fields for output_data_cfg values; see template strings listed in Config Item / Building Block Template Substitution Strings marked as writable (W)

Exceptions
UNSUPPORTED-CONTEXT-ERRORif output data configuration specifies an unsupported context
OUTPUT-CONFIG-ERRORfield_name is not present in all_output_data
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
SET-ORDER-KEYS-ERRORmissing value for order key
INVALID-WORKFLOW-KEYworkflow key not valid for the current workflow
DUPLICATE-KEY-VALUEduplicate value provided for order key
See also
Since
Qorus 4.0.3

◆ usleep()

static int OMQ::UserApi::UserApi::usleep ( softint  arg)
static

puts the current thread to sleep for a certain number of microseconds

If the job, workflow execution instance, or service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or sleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of microseconds to sleep (1 microsecond = 1/1000000 of a second)
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

The documentation for this class was generated from the following file: