Qorus Integration Engine® Enterprise Edition 6.1.0_prod
Loading...
Searching...
No Matches
OMQ::UserApi::UserApi Class Reference

main common Qorus API class More...

Inheritance diagram for OMQ::UserApi::UserApi:
[legend]
Collaboration diagram for OMQ::UserApi::UserApi:
[legend]

Static Public Member Methods

static *hash< auto > getUserServiceInfo (string name)
 returns information about the given user service (if it's currently loaded)
 
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
 
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
 
static hash< auto > getSqlCacheInfo ()
 get information about cached object
 
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)
 
static clearSqlTableCache (AbstractDatasource datasource, *string table_name)
 clears cached objects for given datasource (for example, if database objects have been updated in the dataserver)
 
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.
 
static list< auto > getValueMaps ()
 Gets all value maps valid for the current interface.
 
static bool postSlaEventSuccess (string sla, number value)
 posts a successful SLA event for SLA monitoring and performance tracking
 
static bool postSlaEventError (string sla, number value, string err, string desc)
 posts an unsuccessful SLA event for SLA monitoring and performance tracking
 
static flushSlaEvents ()
 flushes all pending SLA events to disk and returns after the data has been committed
 
static *hash< auto > getSystemServiceInfo (string name)
 returns information about the given system service (if it's currently loaded)
 
static *hash< auto > getServiceInfo (string type, string name)
 returns information about the given service (if it's currently loaded)
 
static list getRunningWorkflowList (*string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances
 
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
 
static softint createOrder (string name, *string version, hash< auto > params, string status=StatReady)
 creates a workflow order data instance in the database
 
static softint createOrder (int wfid, hash< auto > params, string status=StatReady)
 creates a workflow order data instance in the database
 
static softint createRemoteOrder (string remote, string name, *string version, hash< auto > params, string status=StatReady, bool register_dependency=True)
 creates a workflow order data instance in a remote Qorus instance
 
static softint createRemoteOrder (string remote, int wfid, hash< auto > params, string status=StatReady, bool register_dependency=True)
 creates a workflow order data instance in a remote Qorus instance
 
static hash< auto > execSynchronousWorkflow (string name, *string version, hash< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > 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
 
static hash< auto > execSynchronousWorkflow (int wfid, hash< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > 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
 
static hash< auto > execSynchronousWorkflowAsync (string name, *string version, hash< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > orderkeys, *softstring external_order_instanceid, *softint parent_workflow_instanceid)
 executes a workflow order synchronously in the background and returns immediately
 
static hash< auto > execSynchronousWorkflowAsync (int wfid, hash< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > orderkeys, *softstring external_order_instanceid, *softint parent_workflow_instanceid)
 executes a workflow order synchronously in the background and returns immediately
 
static int postUserEvent (string severity, auto info)
 posts an application event of class OMQ::QE_CLASS_USER
 
static hash runtimeProperties ()
 returns Qorus runtime properties as a hash
 
static auto callNetworkApiArgsWithAuthentication (string user, string pass, string call, softlist< auto > args)
 calls a system RPC API with authentication information (username and password)
 
static auto callNetworkApiArgs (string call, *softlist< auto > args)
 calls a system RPC API and returns the respose
 
static auto callNetworkApi (string call,...)
 calls a system RPC API and returns the result; the API is called with system permissions (no restrictions)
 
static auto callRestApi (string method, string path, *hash< auto > body_args)
 calls a system REST API method and returns the result
 
static auto callRestApiWithAuthentication (string user, string pass, string method, string path, *hash< auto > body_args)
 calls a system REST API method with authentication information and returns the result
 
static hash< auto > getSystemInfo ()
 returns a hash of system info
 
static int getSessionId ()
 returns the current Qorus application session ID
 
static startCapturingObjectsFromJava ()
 Starts capturing Qore objects created from Java APIs in the current interface's object cache.
 
static stopCapturingObjectsFromJava ()
 Stops capturing Qore objects created from Java APIs in the current interface's object cache.
 
static startCapturingObjectsFromPython ()
 Starts capturing Qore objects created from Python APIs in the current interface's object cache.
 
static stopCapturingObjectsFromPython ()
 Stops capturing Qore objects created from Python APIs in the current interface's object cache.
 
static saveObjectInObjectCache (object obj)
 Saves the object in the object cache.
 
static bool clearObjectFromObjectCache (object obj)
 Removes the object from the object cache.
 
static *date checkObjectCache (object obj)
 Returns the date/time the object was cached or NOTHING if the object is not in the cache.
 
static int getObjectCacheSize ()
 Returns the number of objects in the cache.
 
static int clearObjectCache ()
 Clears the entire the object cache.
 
static int clearObjectCache (date cutoff)
 Clears the entire the object cache for all objects cached before the given date/time.
 
static list< hash< CallStackInfo > > getThreadCallStack ()
 Allows the current thread's call stack to be retrieved in Qorus.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
static logWithLevel (Logger::LoggerLevel level, string msg,...)
 Writes to the current interface log file with the given log level.
 
static logWithLevel (int level, string msg,...)
 Writes to the current interface log file with the given log level.
 
static logWithLevelArgs (Logger::LoggerLevel level, string msg, *softlist< auto > args)
 Writes to the current interface log file with the given log level.
 
static logWithLevelArgs (int level, string msg, *softlist< auto > args)
 Writes to the current interface log file with the given log level.
 
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.
 
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.
 
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.
 
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.
 
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.
 
static *int auditUserEvent (string user_event, *string info1, *string info2)
 creates a user audit event (with audit code AE_USER_EVENT) against the workflow, service, or job instance
 
static bool auditCheckEventString (string opt)
 checks if the given audit event (given as a string) is enabled
 
static bool auditCheckEvent (softint opt)
 checks if the given audit event (given as an integer code) is enabled
 
static int auditGetMask ()
 returns the audit event mask
 
static bool isKubernetes ()
 returns True when Qorus is running under Kubernetes
 
static int usleep (date arg)
 puts the current thread to sleep for a certain number of microseconds
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds
 
static hash< auto > getQorusOptions (...)
 returns the value of the given system option or options
 
static hash< auto > getQorusOptionInfo (...)
 returns a hash giving information about system options
 
static hash< auto > getQorusOptionInfoArgs (*list< auto > args)
 returns a hash giving information about system options
 
static auto getQorusOptionsArgs (softlist< auto > args)
 returns the value of the given system option or options
 
static hash< auto > getActiveJobs ()
 Returns information on all active jobs visible to the calling user.
 
static object getUserConnection (string name, bool connect=True, bool register_dependency=True, *hash< auto > rtopts)
 Returns an object corresponding to a defined user connection.
 
static hash< auto > getUserConnectionTags (string name)
 Returns any tags set on the given user connection.
 
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
 
static AbstractDatasource getDatasourcePool (string name, bool register_dependency=True)
 returns a DatasourcePool object for the given datasource name
 
static hash< auto > getDatasourceInfo (string name)
 returns a hash of information for the given datasource, if known, otherwise throws an exception
 
static QorusSystemAPIHelper getRemoteRpcConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus remote connection.
 
static QorusSystemRestHelper getRemoteRestConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemRestHelper object corresponding to a defined Qorus remote connection.
 
static raiseTransientAlert (string alert, string reason, *hash< auto > info)
 raises a transient system alert from a workflow, service, or job
 
static string qorusGetPublicUrl (*hash< auto > cx)
 Returns a string giving the remote / publicly-accessble system URL.
 
static string qorusGetLocalUrl (*string username, *string password)
 returns a string giving the local system URL
 
static setOption (hash< auto > hash)
 Changes option values on a workflow, service, or job.
 
static auto getOption (...)
 Returns the value of the named workflow, service, or job option or options.
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named workflow, service, or job option or options.
 
static hash< auto > blockOrder (softint wfiid)
 block the given workflow order data instance
 
static hash< auto > unblockOrder (softint wfiid, *hash< auto > tempdata, *hash< auto > orderkeys)
 unblocks the given workflow order data instance
 
static hash< auto > cancelOrder (softint wfiid)
 cancel the given workflow order data instance
 
static hash< auto > uncancelOrder (softint wfiid, *hash< auto > tempdata)
 uncancels the given workflow order data instance
 
static updateDynamicOrderData (softint wfiid, hash< auto > new_data)
 updates the given workflow order instance's dynamic data hash atomically
 
static updateDynamicOrderDataPath (softint wfiid, string path, auto value)
 updates the given workflow order instance's dynamic data hash atomically
 
static *hash< auto > getUserContextInfo ()
 returns a hash for the current user context
 
static *string getContextUserName ()
 returns the current username for any external user-initiated call or NOTHING if executing in a system context
 
static auto getConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
 returns config item value in the current user context
 
static auto getInterfaceConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
 returns config item value in the current interface context
 
static hash< auto > getConfigItemHash (*hash< auto > local_context)
 returns a hash of all configuration items for the current interface
 
static hash< auto > getInterfaceConfigItemHash (*hash< auto > local_context)
 Returns a hash of all configuration items for the current context as a combination of local and global configuration items.
 
static auto getGlobalConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
 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
 
static auto getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context, bool expand_complex_values=True)
 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
 
static AbstractDataProvider getDataProvider (hash< auto > h, *hash< auto > ctx)
 Returns a data provider corresponding to the hash description.
 
static AbstractDataProvider getDataProvider (string path)
 returns the data provider given by a path string
 
static AbstractDataProvider getDataProvider (string type, string name, *string path, *hash< auto > opts, *hash< auto > ctxt, *bool handle_template_args)
 returns the data provider given by a path string
 
static AbstractDataProviderType getQorusType (string type_path)
 Returns a data provider type from a direct type path.
 
static AbstractDataProviderType getType (hash< auto > h, *hash< auto > ctx)
 Returns a type corresponding to the hash description.
 
static AbstractDataProviderType getType (string typename, string name, *string path, *string subtype, *string subtypename, *hash< auto > options, *hash< auto > ctx)
 Returns a type corresponding to the arguments.
 
static AbstractDataProviderType getTypeFromPath (string path)
 returns a data provider type identified by a path string
 
static Mapper::Mapper getMapper (string name, *hash< auto > rtopts)
 returns the given mapper if registered for the current interface
 
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
 
static bool postSyncEvent (string eventtype, string eventkey)
 posts a workflow synchronization event given the event type name and the unique event key
 
static hash< auto > propGet ()
 returns a hash of all system properties in all domains
 
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
 
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
 
static string propUpdate (string domain, softstring key, auto value)
 changes (inserts, updates, or deletes) the value of a single system property
 
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
 
static softint getNextSequenceValue (AbstractDatasource ds, string name)
 returns the next sequence value for the given datasource and sequence
 
static softint getNextSequenceValue (string ds, string name)
 returns the next sequence value for the given datasource and sequence
 
static string serializeQorusData (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus
 
static string serializeQorusDataWithNothing (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus
 
static auto deserializeQorusData (string data)
 parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data
 
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
 
static bool isInternalSystemDebuggingEnabled ()
 returns True if internal system debugging is enabled
 
static auto getHashDotValue (*hash< auto > var_data, string var_name, *reference< bool > missing_input)
 returns the value of the given key from the given hash, respects dot notation in the key name
 
static auto expandOneVariable (string str, string var_context, auto template_arg, *hash< auto > local_context, *bool brackets, bool expand_complex_values=True, *reference< bool > missing_input)
 expands one variable in a templated string
 
static bool isSingleTemplatedString (auto value)
 checks if the given value is a templated string with only one expandable variable
 
static auto expandTemplatedValue (auto value, *hash< auto > local_context, bool expand_complex_values=True, *reference< bool > missing_input, *string template_context)
 expands all variables in a templated string
 
static softlist< auto > expandComplexValue (list< auto > val, *hash< auto > local_context, *string template_context)
 expands all variables in a list with templated values
 
static hash< auto > expandComplexValue (hash< auto > val, *hash< auto > local_context, *string template_context)
 expands all variables in a hash with templated values
 
static hash< BbVariable > bbParseExactlyOneVariable (string str)
 parses one template variable and returns a hash with its parts
 
static auto getInputData (string field_name, *hash< auto > local_context, *hash< auto > input_data_cfg)
 returns specified input data field's value
 
static hash< auto > getInputData (*hash< auto > input_data_cfg, *hash< auto > local_context)
 returns all input data
 
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
 
static *hash< auto > deleteHashDotValue (*hash< auto > var_data, string var_name, *bool recursive)
 Updates the given hash by deleting the value described by a key in dot notation.
 
static updateOutputData (string field_name, auto output_data, *hash< auto > output_data_cfg)
 updates specified output data field's value
 
static updateOutputData (hash< auto > all_output_data, hash< auto > output_data_cfg=UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY, NOTHING, False))
 updates all output data
 
static writeOutputData (*hash< auto > output_data)
 Writes output data using a concise format.
 
static string getTextFileFromLocation (string location)
 returns string data for the given file location
 
static binary getBinaryFileFromLocation (string location)
 returns binary data for the given file location
 
static Qore::StreamReader getStreamReaderFromLocation (string location)
 Returns a string stream for the file's data at the given location.
 
static Qore::InputStream getBinaryStreamFromLocation (string location)
 Returns an input stream for file data at the given location.
 
static writeFileToLocation (string location, data contents)
 Writes data to a file at the given location.
 
static FileLocationHandler::OutputStreamWrapper getOutputStreamForLocation (string location)
 Returns an output stream for writing data to the given location.
 
static auto executeFsm (string fsm_name, auto arg)
 Executes the given Finite State Machine and returns the final output.
 
static registerFsmAsObserver (string fsm_name, DataProvider::Observable observable, string event_id)
 Registers the given Finite State Machine with the given object as an Observer.
 
static string generateTokenForUser (string username, timeout expiry=DefaultTokenExpirationPeriod)
 Generates an access token for the given user with the given expiration time.
 
static string generateTokenForUser (string username, int expiry_seconds)
 Generates an access token for the given user with the given expiration time.
 
static bool invalidateToken (string token)
 Invalidates the given token.
 
static refreshToken (string token, *int expiry_seconds)
 Refreshes the given token.
 
static refreshToken (string token, timeout expiry_seconds)
 Refreshes the given token.
 
static *hash< TokenInfogetTokenInfo (string token, *bool refresh_token)
 Returns information for the given token.
 
static *hash< QorusUserInfogetCurrentUserInfo ()
 Returns information for the current user.
 
static hash< QorusUserInfogetUserInfo (*string username)
 Returns information for the given user.
 
hash< auto > bindSubworkflow (hash< auto > wf, hash< auto > order)
 This method binds a workflow to a subworkflow step.
 
hash< auto > skipSubworkflow ()
 This method skips binding a workflow to a subworkflow step.
 
 submitAsyncKey (string key)
 Binds the given key to the asynchronous step.
 
 skipAsyncStep ()
 This method will skip the execution of an asynchronous step.
 
 bindEvent (string eventkey)
 binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent)
 
 bindEventUnposted (string eventkey)
 binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) only if the event has not yet been posted; if the event has already been posted, then an ALREADY-POSTED exception is raised
 
 skipEvent ()
 skips a workflow synchronization event step
 
static leaveParentFeedback (string key, auto value)
 leaves feedback for a parent workflow
 
static auto getChildFeedback (string key)
 gets feedback from a child workflow order with the given key
 
static bool isWorkflowContext ()
 Returns True if the code is executing in an immediate workflow context, False if not.
 
static bool isServiceContext ()
 Returns True if the code is executing in an immediate service context, False if not.
 
static bool isJobContext ()
 Returns True if the code is executing in an immediate job context, False if not.
 

Static Private Member Methods

static QorusProgram DynamicLogic (False, CommonParseOptions|PO_NO_INHERIT_USER_CLASSES|PO_NO_INHERIT_USER_FUNC_VARIANTS|PO_NO_INHERIT_GLOBAL_VARS|PO_NO_INHERIT_USER_CONSTANTS|PO_NO_INHERIT_USER_HASHDECLS|PO_NEW_STYLE|PO_STRICT_ARGS|PO_REQUIRE_TYPES, QorusServerDefines)
 Program for dynamic logic.
 

Private Attributes

const DataProviderRootValues
 data provider root path values
 
const DataTypeRootValues
 data type root path values
 
const DataProviderPathTypeValues
 data type path provider type values
 

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
Note
This API is not available in the client library

◆ 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
Note
This API is not available in the client library

◆ auditGetMask()

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

returns the audit event mask

Returns
the audit event mask
Note
This API is not available in the client library

◆ auditUserEvent()

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

creates a user audit event (with audit 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
  • This API is not available in the client library

◆ 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

◆ bindEvent()

OMQ::UserApi::UserApi::bindEvent ( string  eventkey)
static

binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent)

This call is a wrapper for QorusEventStepBase::bindEvent(); please see that method for documentation

Exceptions
EVENT-STEP-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ bindEventUnposted()

OMQ::UserApi::UserApi::bindEventUnposted ( string  eventkey)
static

binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) only if the event has not yet been posted; if the event has already been posted, then an ALREADY-POSTED exception is raised

This call is a wrapper for QorusEventStepBase::bindEventUnposted(); please see that method for documentation

Exceptions
EVENT-STEP-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ bindSubworkflow()

hash< auto > OMQ::UserApi::UserApi::bindSubworkflow ( hash< auto >  wf,
hash< auto >  order 
)
static

This method binds a workflow to a subworkflow step.

This call is a wrapper for QorusSubworkflowStepBase::bindSubworkflow(); please see that method for documentation

Exceptions
SUBWORKFLOW-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ 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

◆ 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
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
Note
This API is not available in the client library
See also

◆ callNetworkApiArgs()

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

calls a system RPC API and returns the respose

The argument list to the API method is passed as a single 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
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
Note
This API is not available in the client library
See also

◆ callNetworkApiArgsWithAuthentication()

static auto OMQ::UserApi::UserApi::callNetworkApiArgsWithAuthentication ( string  user,
string  pass,
string  call,
softlist< auto >  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
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
Note
This API is not available in the client library
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 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"
  • This API is not available in the client library
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

◆ checkObjectCache()

static *date OMQ::UserApi::UserApi::checkObjectCache ( object  obj)
static

Returns the date/time the object was cached or NOTHING if the object is not in the cache.

Parameters
objthe object to check
Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Since
Qorus 4.1

◆ clearObjectCache() [1/2]

static int OMQ::UserApi::UserApi::clearObjectCache ( )
static

Clears the entire the object cache.

Returns
the number of objects cleared from the cache
Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Since
Qorus 4.1

◆ clearObjectCache() [2/2]

static int OMQ::UserApi::UserApi::clearObjectCache ( date  cutoff)
static

Clears the entire the object cache for all objects cached before the given date/time.

Returns
the number of objects cleared from the cache
Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Since
Qorus 4.1

◆ clearObjectFromObjectCache()

static bool OMQ::UserApi::UserApi::clearObjectFromObjectCache ( object  obj)
static

Removes the object from the object cache.

Returns
True if the object was removed, False if it was not in the cache
Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Since
Qorus 4.1

◆ clearSqlTableCache() [1/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
Note
This API is not available in the client library
See also

◆ clearSqlTableCache() [2/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");
Note
This API is not available in the client library

See

◆ createOrder() [1/2]

static softint OMQ::UserApi::UserApi::createOrder ( int  wfid,
hash< auto >  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
wfidthe ID of the workflow
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 OMQ::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 OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::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:
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
Since
Qorus 6.1

◆ createOrder() [2/2]

static softint OMQ::UserApi::UserApi::createOrder ( string  name,
*string  version,
hash< auto >  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 OMQ::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 OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::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:
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() [1/2]

static softint OMQ::UserApi::UserApi::createRemoteOrder ( string  remote,
int  wfid,
hash< auto >  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
wfidthe ID of the workflow
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 OMQ::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 OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::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:
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
Since
Qorus 6.1

◆ createRemoteOrder() [2/2]

static softint OMQ::UserApi::UserApi::createRemoteOrder ( string  remote,
string  name,
*string  version,
hash< auto >  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 OMQ::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 OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::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:
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

◆ deleteHashDotValue()

static *hash< auto > OMQ::UserApi::UserApi::deleteHashDotValue ( *hash< auto >  var_data,
string  var_name,
*bool  recursive 
)
static

Updates the given hash by deleting the value described by a key in dot notation.

Example:
hash<auto> updated_hash = UserApi::deleteHashDotValue({}, "account.id");
Parameters
var_datathe hash to update
var_namethe key name to delete in dot notation
recursivedelete affected hash keys if there are no more child keys
Returns
the updated hash
Since
Qorus 6.1

◆ 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() [1/2]

static hash< auto > OMQ::UserApi::UserApi::execSynchronousWorkflow ( int  wfid,
hash< auto >  sdata,
*hash< auto >  opts,
*hash< auto >  ddata,
softint  priority = DefaultOrderPriority,
*hash< auto >  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
wfidthe workflow ID
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:
  • workflow_instanceid (int): the workflow order instance ID
  • status (string): the order status commit to the database (for possible values, see Workflow, Segment, and Step Status Descriptions)
  • dynamicdata (*hash): the order's dynamic data hash, if any
  • [error (string)]: the last error for the order, if any
  • [description (string)]: the last error description for the order, if any
  • [info (*hash)]: the last error info hash for the order, if any
Note
This API is not available in the client library
Since
Qorus 6.1

◆ execSynchronousWorkflow() [2/2]

static hash< auto > OMQ::UserApi::UserApi::execSynchronousWorkflow ( string  name,
*string  version,
hash< auto >  sdata,
*hash< auto >  opts,
*hash< auto >  ddata,
softint  priority = DefaultOrderPriority,
*hash< auto >  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:
  • workflow_instanceid (int): the workflow order instance ID
  • status (string): the order status commit to the database (for possible values, see Workflow, Segment, and Step Status Descriptions)
  • dynamicdata (*hash): the order's dynamic data hash, if any
  • [error (string)]: the last error for the order, if any
  • [description (string)]: the last error description for the order, if any
  • [info (*hash)]: the last error info hash for the order, if any
Note
This API is not available in the client library

◆ execSynchronousWorkflowAsync() [1/2]

static hash< auto > OMQ::UserApi::UserApi::execSynchronousWorkflowAsync ( int  wfid,
hash< auto >  sdata,
*hash< auto >  opts,
*hash< auto >  ddata,
softint  priority = DefaultOrderPriority,
*hash< auto >  orderkeys,
*softstring  external_order_instanceid,
*softint  parent_workflow_instanceid 
)
static

executes a workflow order synchronously in the background and returns immediately

The order will be executed by the given workflow synchronously in the background; this API returns the workflow instance ID and the workflow execution ID used to execute the order

Parameters
wfidthe workflow ID
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 asynchronous order execution information with the following keys:
  • workflow_instanceid (int): the workflow order instance ID
  • execid (int): the synchronous workflow execution instance ID
Note
This API is not available in the client library
Since
Qorus 6.1

◆ execSynchronousWorkflowAsync() [2/2]

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

executes a workflow order synchronously in the background and returns immediately

The order will be executed by the given workflow synchronously in the background; this API returns the workflow instance ID and the workflow execution ID used to execute the order

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 asynchronous order execution information with the following keys:
  • workflow_instanceid (int): the workflow order instance ID
  • execid (int): the synchronous workflow execution instance ID
Note
This API is not available in the client library
Since
Qorus 6.1

◆ executeFsm()

static auto OMQ::UserApi::UserApi::executeFsm ( string  fsm_name,
auto  arg 
)
static

Executes the given Finite State Machine and returns the final output.

Parameters
fsm_namethe name of the Finite State Machine to execute; must be a valid Finite State Machine for the current interface context
argany optional input argument for the Finite State Machine
Returns
any final output provided by the Finite State Machine
Exceptions
FSM-NOT-FOUNDThe given Finite State Machine is not valid for the current interface context
Note
This API is not available in the client library
Since
Qorus 5.0

◆ expandComplexValue() [1/2]

static hash< auto > OMQ::UserApi::UserApi::expandComplexValue ( hash< auto >  val,
*hash< auto >  local_context,
*string  template_context 
)
static

expands all variables in a hash with templated values

Parameters
valthe value to expand
local_contextlocal context supplied by the caller (plus user context info is added - see UserApi::getUserContextInfo() method)
template_contextoptional template context
Returns
the value with templated strings expanded
Exceptions
VALUE-ERRORif the key in a hash is not resolved to a type convertible to a string
See also
expandTemplatedValue() for information about how strings are expanded
Since
Qorus 4.1.1

◆ expandComplexValue() [2/2]

static softlist< auto > OMQ::UserApi::UserApi::expandComplexValue ( list< auto >  val,
*hash< auto >  local_context,
*string  template_context 
)
static

expands all variables in a list with templated values

Parameters
valthe value to expand
local_contextlocal context supplied by the caller (plus user context info is added - see UserApi::getUserContextInfo() method)
template_contextoptional template context
Returns
the value with templated strings expanded
Exceptions
VALUE-ERRORif the key in a hash is not resolved to a type convertible to a string
See also
expandTemplatedValue() for information about how strings are expanded
Since
Qorus 4.1.1

◆ expandOneVariable()

static auto OMQ::UserApi::UserApi::expandOneVariable ( string  str,
string  var_context,
auto  template_arg,
*hash< auto >  local_context,
*bool  brackets,
bool  expand_complex_values = True,
*reference< bool >  missing_input 
)
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,...)
template_argthe template argument for the given context
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; currently ignored
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
missing_inputan optional reference that returns True if the input key was missing in case of a NOTHING return value
Returns
the specified variable expanded to its value
Exceptions
LIST-VALUE-ERRORcannot parse list value expression
REST-EXPRESSION-ERRORcannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
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
  • added in Qorus 4.0.3
  • Qorus 4.1 removed the UNKNOWN-VALUE-ERROR exception
  • Qorus 4.1.1 added the expand_complex_values parameter

◆ expandTemplatedValue()

static auto OMQ::UserApi::UserApi::expandTemplatedValue ( auto  value,
*hash< auto >  local_context,
bool  expand_complex_values = True,
*reference< bool >  missing_input,
*string  template_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)
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
missing_inputan optional reference that returns True if the input key was missing in case of a NOTHING return value
template_contextoptional template context
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
LIST-VALUE-ERRORcannot parse list value expression
REST-EXPRESSION-ERRORcannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
FORMAT-ERRORif the templated string doesn't have correct format (e.g. unescaped dollar sign that does not represent a variable)
VALUE-ERRORif the resolved values cannot be combined for the return value. or if the key in a hash is not resolved to a type convertible to a string
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
  • added in Qorus 4.0.3
  • Qorus 4.1 removed the UNKNOWN-VALUE-ERROR exception
  • Qorus 4.1.1 added the expand_complex_values argument
  • Qorus 5.1.21 added the template_context argument

◆ 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();
Note
This API is not available in the client library

◆ generateTokenForUser() [1/2]

static string OMQ::UserApi::UserApi::generateTokenForUser ( string  username,
int  expiry_seconds 
)
static

Generates an access token for the given user with the given expiration time.

Parameters
usernamethe user to generate the token for
expiry_secondsthe expiration time of the token
Returns
the new token for the user
Note
The username is not validated; tokens can be returned for invalid users
See also
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ generateTokenForUser() [2/2]

static string OMQ::UserApi::UserApi::generateTokenForUser ( string  username,
timeout  expiry = DefaultTokenExpirationPeriod 
)
static

Generates an access token for the given user with the given expiration time.

Parameters
usernamethe user to generate the token for
expirythe expiration time of the token with a resolution of one second
Returns
the new token for the user
Note
The username is not validated; tokens can be returned for invalid users
See also
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ 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
  • [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
Note
This API is not available in the client library

◆ 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"); see File Locations for more information about this parameter
Returns
the resource data as a binary value
Exceptions
LOCATION-ERRORthe location string cannot be parsed; unknown location scheme; invalid location option
Since

◆ getBinaryStreamFromLocation()

static Qore::InputStream OMQ::UserApi::UserApi::getBinaryStreamFromLocation ( string  location)
static

Returns an input stream for file data at the given location.

Parameters
locationthe location of the file data
Returns
an input stream for the file's data
Since
Qorus 5.1.24

◆ getChildFeedback()

static auto OMQ::UserApi::UserApi::getChildFeedback ( string  key)
static

gets feedback from a child workflow order with the given key

This call is a wrapper for WorkflowApi::getChildFeedback(); please see that method for documentation

Exceptions
FEEDBACK-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 6.0

◆ getConfigItemHash()

static hash< auto > OMQ::UserApi::UserApi::getConfigItemHash ( *hash< auto >  local_context)
static

returns a hash of all configuration items for the current interface

Example:
hash<auto> config = UserApi::getConfigItemHash();
Parameters
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
a hash of all configuration items for the current interface; keys are config item names; values are config item values. If there are no config items for the current interface, then an empty hash is returned.
Note
  • If there are local configuration item values and values on global level, the local values will take precedence over the global values
  • The value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution - In a @ref data_pipeline_processors "pipeline processor" or a @ref fsm_data_processing "finite state machine connector", this method will return config item information from the @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine" only; config item information from the interface is not accessible; use @ref getInterfaceConfigItemHash() to get configuration information from the interface from within a @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine"
See also
getInterfaceConfigItemHash()
Note
This API is not available in the client library
Since
Qorus 4.0.3

◆ getConfigItemValue()

static auto OMQ::UserApi::UserApi::getConfigItemValue ( string  cfg_item,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
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)
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
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 - In a @ref data_pipeline_processors "pipeline processor" or a @ref fsm_data_processing "finite state machine connector", this method will return config item information from the @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine" only; config item information from the interface is not accessible; use @ref getInterfaceConfigItemHash() to get configuration information from the interface from within a @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine"
See also
getInterfaceConfigItemValue()
Since
  • Qorus 4.0.3
  • Qorus 4.1.1 added the expand_complex_values parameter

◆ getContextUserName()

static *string OMQ::UserApi::UserApi::getContextUserName ( )
static

returns the current username for any external user-initiated call or NOTHING if executing in a system context

Returns
the current username for any external user-initiated call or NOTHING if executing in a system context
Note
This API is not available in the client library
Since
Qorus 4.1

◆ getCurrentUserInfo()

static *hash< QorusUserInfo > OMQ::UserApi::UserApi::getCurrentUserInfo ( )
static

Returns information for the current user.

Returns
information for the current user; if there is no current user, then NOTHING is returned
Note
This API is not available in the client library
Since
Qorus 5.1.20

◆ getDataProvider() [1/3]

static AbstractDataProvider OMQ::UserApi::UserApi::getDataProvider ( hash< auto >  h,
*hash< auto >  ctx 
)
static

Returns a data provider corresponding to the hash description.

Parameters
ha description of the data provider with keys as follows:
  • type: the source of the data provider; one of the following values:
  • name: the name of the type
  • path: an optional data provider path to the data provider
  • options: an optional hash of data provider factory creation options; invalid options are ignored; these options, if present, are also processed with expandTemplatedValue() using ctx as the local context value
ctxany local context to use when processing opts with expandTemplatedValue(); if not present, defaults to getUserContextInfo()
Since
Qorus 6.0.11

◆ getDataProvider() [2/3]

static AbstractDataProvider OMQ::UserApi::UserApi::getDataProvider ( string  path)
static

returns the data provider given by a path string

Example:
AbstractDataProvider d = UserApi::getDataProvider("connection/rest-billing-1/accounts/POST");
Parameters
paththe path to the dataprovider; the first element must be one of the following:
  • factory: for data provider factory objects (ex: "factory/cvswrite{path=/tmp/file.csv}")
  • connection: for user connections
  • datasource: for datasources
  • remote: for Qorus remote connections
    The second element should be the name of the connection, and further elements should be the path to the data provider.
Exceptions
DATA-PROVIDER-ERRORthe given data provider path is unknown or invalid
Since
Qorus 4.1

◆ getDataProvider() [3/3]

static AbstractDataProvider OMQ::UserApi::UserApi::getDataProvider ( string  type,
string  name,
*string  path,
*hash< auto >  opts,
*hash< auto >  ctxt,
*bool  handle_template_args 
)
static

returns the data provider given by a path string

Example:
AbstractDataProvider d = UserApi::getDataProvider("connection", "rest-billing-1", "/accounts/POST");
Parameters
typemust be one of the following:
namethe name of the type
pathan optional data provider path to the data provider
optsany optional data provider factory creation options; invalid options are ignored; these options, if present, are also processed with expandTemplatedValue() using ctxt as the local context value
ctxtany local context to use when processing opts with expandTemplatedValue()
handle_template_argscallers can use True here in non-runtime contexts so that any template arguments can be separated and data provider factories can try to create objects without runtime values
Exceptions
DATA-PROVIDER-ERRORa data provider could not be created from the arguments
Since
  • Qorus 6.0
  • Qorus 6.0.3 added the handle_template_args argument

◆ 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
Note
When used in the Qorus client, this method also will implicitly initialize the client library
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
Note
This API is not available in the client library

◆ 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
Note
When used in the Qorus client, this method also will implicitly initialize the client library
See also

◆ getGlobalConfigItemValue()

static auto OMQ::UserApi::UserApi::getGlobalConfigItemValue ( string  item,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
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)
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
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
  • This API is not available in the client library
Since
  • Qorus 4.0.3
  • Qorus 4.1.1 added the expand_complex_values parameter
See also
getGlobalConfigItemValueWithDefault()

◆ getGlobalConfigItemValueWithDefault()

static auto OMQ::UserApi::UserApi::getGlobalConfigItemValueWithDefault ( string  item,
auto  default_value,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
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)
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
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
  • The value is always substituted with UserApi::expandTemplatedValue()
  • If the config item is not set, default_value is returned after substitutions with UserApi::expandTemplatedValue()
  • Make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
  • This API is not available in the client library
Since
  • Qorus 4.0.3
  • Qorus 4.1.1 added the expand_complex_values parameter
See also
getGlobalConfigItemValue()

◆ getHashDotValue()

static auto OMQ::UserApi::UserApi::getHashDotValue ( *hash< auto >  var_data,
string  var_name,
*reference< bool >  missing_input 
)
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
missing_inputan optional reference that returns True if the input key was missing in case of a NOTHING return value
Returns
the value referenced or NOTHING if not present
Since
Qorus 4.0.3

◆ getInputData() [1/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
LIST-VALUE-ERRORcannot parse list value expression
REST-EXPRESSION-ERRORcannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERRORif an unknown or invalid context variable is specified to be expanded
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
  • added in Qorus 4.0.3
  • Qorus 4.1 removed the UNKNOWN-VALUE-ERROR exception

◆ getInputData() [2/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
LIST-VALUE-ERRORcannot parse list value expression
REST-EXPRESSION-ERRORcannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
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
  • added in Qorus 4.0.3
  • Qorus 4.1 removed the UNKNOWN-VALUE-ERROR exception

◆ getInterfaceConfigItemHash()

static hash< auto > OMQ::UserApi::UserApi::getInterfaceConfigItemHash ( *hash< auto >  local_context)
static

Returns a hash of all configuration items for the current context as a combination of local and global configuration items.

Example:
hash<auto> config = UserApi::getInterfaceConfigItemHash();
Parameters
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
a hash of all configuration items for the current context; keys are config item names; values are config item values. If there are no config items for the current context, then an empty hash is returned.
Note
  • The value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution - In a @ref data_pipeline_processors "pipeline processor" or a @ref fsm_data_processing "finite state machine connector", this method will return config item information from the @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine" only; config item information from the interface is not accessible; use @ref getInterfaceConfigItemHash() to get configuration information from the interface from within a @ref data_pipelines "data pipeline" or @ref finite_state_machines "finite state machine"
  • This API is not available in the client library
See also
getConfigItemHash()
Since
Qorus 5.0

◆ getInterfaceConfigItemValue()

static auto OMQ::UserApi::UserApi::getInterfaceConfigItemValue ( string  cfg_item,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
static

returns config item value in the current interface 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)
expand_complex_valuesif True then lists and hashes will have their values expanded recursively
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 - In a @ref data_pipeline_processors "pipeline processor" or a @ref fsm_data_processing "finite state machine connector", this function will return config item information from the interface; config item information from the @ref data_pipelines "data pipeline" and @ref finite_state_machines "finite state machine" is not accessible; use @ref getConfigItemValue() to get configuration information from @ref data_pipelines "data pipelines" and @ref finite_state_machines "finite state machines"
See also
getConfigItemValue()
Since
  • Qorus 5.0

◆ 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
Note
This API is not available in the client library
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
Note
This API is not available in the client library
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
Note

◆ 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

◆ getObjectCacheSize()

static int OMQ::UserApi::UserApi::getObjectCacheSize ( )
static

Returns the number of objects in the cache.

Returns
the number of objects in the cache
Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Since
Qorus 4.1

◆ 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
This API is not available in the client library
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
This API is not available in the client library
See also

◆ getOutputStreamForLocation()

static FileLocationHandler::OutputStreamWrapper OMQ::UserApi::UserApi::getOutputStreamForLocation ( string  location)
static

Returns an output stream for writing data to the given location.

Parameters
locationthe location of the file to write
Returns
an output stream for writing to the file
Note
  • OutputStreamWrapper::close() must be called to close the stream after writing terminates in order to avoid a deadlock
  • The data written to the OutputStreamWrapper object may be written in the background; to ensure that the data has been written to the target, call OutputStreamWrapper::waitForIo()
Since
Qorus 5.1.24

◆ getQorusOptionInfo()

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

returns a hash giving information about system options

Note
This API is not available in the client library

◆ getQorusOptionInfoArgs()

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

returns a hash giving information about system options

Note
This API is not available in the client library

◆ getQorusOptions()

static hash< auto > OMQ::UserApi::UserApi::getQorusOptions (   ...)
static

returns the value of the given system option or options

Examples
# return all options
hash<auto> all_options = UserApi::getQorusOptions();
# return the value of a single option
string logdir = UserApi::getQorusOptions("logdir").logdir;
# return the values for multiple options
hash<auto> some_options = UserApi::getQorusOptions("logdir", "systemdb");
Parameters
...zero or more options
Returns
the return value depends on the arguments as follows:
  • no arguments: the return value is a hash of all options keyed by option name and the values of those options
  • one or more strings as option names: a hash giving the values of the given options keyed by option name
Note
When used in the Qorus client, this method also will implicitly initialize the client library

◆ getQorusOptionsArgs()

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

returns the value of the given system option or options

Note
This API is not available in the client library

◆ getQorusType()

static AbstractDataProviderType OMQ::UserApi::UserApi::getQorusType ( string  type_path)
static

Returns a data provider type from a direct type path.

Parameters
type_paththe direct path to the type as would be used with DataProvider::getTypeEx()
Returns
the data provider type corresponding to the type
Exceptions
DATA-TYPE-ERRORthe given type is unknown
See also
getTypeFromPath()
Since
Qorus 4.1.2

◆ 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
Note
When used in the Qorus client, this method also will implicitly initialize the client library

◆ 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
Note
When used in the Qorus client, this method also will implicitly initialize the client library

◆ 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: OMQ::WM_Normal or OMQ::WM_Recovery
  • sync: True if the execution instance is synchronous, False if not
  • status: OMQ::WISInitializing, OMQ::WISRunning, OMQ::WISWaiting, OMQ::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
Note
This API is not available in the client library
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: OMQ::WM_Normal or OMQ::WM_Recovery
  • sync: True if the execution instance is synchronous, False if not
  • status: OMQ::WISInitializing, OMQ::WISRunning, OMQ::WISWaiting, OMQ::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
Note
This API is not available in the client library
See also

◆ getServiceInfo()

static *hash< auto > 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: OMQ::SSRunning or OMQ::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 or False if the autostart flag is set
  • manual_autostart: True or 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
Note
This API is not available in the client library

◆ getSessionId()

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

returns the current Qorus application session ID

Returns
the current Qorus application session ID
Note
When used in the Qorus client, this method also will implicitly initialize the client library
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;
Note
This API is not available in the client library
See also

◆ getSqlTable() [1/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

◆ getSqlTable() [2/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("my_datasource", "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

◆ getStreamReaderFromLocation()

static Qore::StreamReader OMQ::UserApi::UserApi::getStreamReaderFromLocation ( string  location)
static

Returns a string stream for the file's data at the given location.

Parameters
locationthe location of the file data
Returns
a stream reader for the file's data
Since
Qorus 5.1.24

◆ getSystemInfo()

static hash< auto > 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 5.1.0, omq-version-code = 50100)
  • 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)
  • omq-driver: the DB driver name for the system schema
  • 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
  • edition: Enterprise for Qorus Integration Engine(R) Enterprise Edition
  • tz_region: the server's time zone region name
  • tz_utc_offset: the UTC offset in seconds east of UTC; negative numbers indicate west of UTC
Note
This API is not available in the client library
Since
Qorus 6.0.0 added the edition, tz_region, and tz_utc_offset keys

◆ 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: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or 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
Note
This API is not available in the client library

◆ 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/ressource"); see File Locations for more information about this parameter
Returns
the resource data as a string
Exceptions
LOCATION-ERRORthe location string cannot be parsed; unknown location scheme; invalid location option
Since

◆ getThreadCallStack()

static list< hash< CallStackInfo > > OMQ::UserApi::UserApi::getThreadCallStack ( )
static

Allows the current thread's call stack to be retrieved in Qorus.

Qore function ref Qore::get_thread_call_stack() is prohibited from use in Qorus interfaces due to sandboxing restrictions

Since
Qorus 4.1

◆ getTokenInfo()

static *hash< TokenInfo > OMQ::UserApi::UserApi::getTokenInfo ( string  token,
*bool  refresh_token 
)
static

Returns information for the given token.

Parameters
tokenthe access token to check
refresh_tokenif True then the token's validity period is refreshed
Returns
information for the given token or NOTHING if the token is invalid
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ getType() [1/2]

static AbstractDataProviderType OMQ::UserApi::UserApi::getType ( hash< auto >  h,
*hash< auto >  ctx 
)
static

Returns a type corresponding to the hash description.

Parameters
ha description of the type with keys as follows:
  • type: the source of the type; one of the following values:
  • name: the name of the type
  • path: an optional data provider path to the data provider
  • options: an optional hash of data provider factory creation options; invalid options are ignored; these options, if present, are also processed with expandTemplatedValue() using ctx as the local context value
  • subtype: an optional subtype for data providers giving the type to retrieve; valid values are:
    • record
    • event
    • message
    • error
  • subtypename: the error, event, or message_id of the type to return; valid with subtypes "error", "event", and "message"
ctxany local context to use when processing opts with expandTemplatedValue(); if not present, defaults to getUserContextInfo()
Since
Qorus 6.1

◆ getType() [2/2]

static AbstractDataProviderType OMQ::UserApi::UserApi::getType ( string  typename,
string  name,
*string  path,
*string  subtype,
*string  subtypename,
*hash< auto >  options,
*hash< auto >  ctx 
)
static

Returns a type corresponding to the arguments.

Parameters
typenamethe source of the type; one of the following values:
namethe name of the type
pathan optional data provider path to the data provider
subtypean optional subtype for data providers giving the type to retrieve; valid values are:
  • record
  • event
  • message
  • error
subtypenamethe error, event, or message_id of the type to return; valid with subtypes "error", "event", and "message"
optionsan optional hash of data provider factory creation options; invalid options are ignored; these options, if present, are also processed with expandTemplatedValue() using ctx as the local context value
ctxany local context to use when processing opts with expandTemplatedValue(); if not present, defaults to getUserContextInfo()
Since
Qorus 6.1

◆ getTypeFromPath()

static AbstractDataProviderType OMQ::UserApi::UserApi::getTypeFromPath ( string  path)
static

returns a data provider type identified by a path string

Example:
AbstractDataProviderType type = UserApi::getTypeFromPath("type/qore/ftp/event");
Parameters
paththe path to the type (which will be normalized; any leading "/" character(s) will be stripped); the first element must be one of the following:
  • type: indicates that the rest of the path identifies a registered data provider type
  • factory: indicates that the rest of the path identifies a data provider provided from a factory (ex: "factory/csvwrite{path=/tmp/file.csv}"
  • connection: indicates that the following path element identifies a user connection
  • datasource: indicates that the following path element identifies a datasource
  • remote: indicates that the following path element identifies a Qorus remote connection
    For type paths in data providers (i.e. connection, datasource, and remote), the path element after the provider must be one of the following:
  • request: for the request type
  • response: for the response type
  • error: for the error response type, in which case the next path element provides the error code
  • record: for the record type
  • message: for the message type, in which case the next path element provides the message ID
  • event: for the observable event type, in which case the next path element provides the event ID
Exceptions
DATA-TYPE-ERRORthe given type is unknown
See also
getQorusType()
Since
Qorus 4.1.1

◆ 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
Note
When used in the Qorus client, this method also will implicitly initialize the client library
See also

◆ getUserConnectionTags()

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

Returns any tags set on the given user connection.

Parameters
namethe name of the connection
Returns
any tags set on the given user connection
Exceptions
CONNECTION-ERRORThe given connection is not known
Note
This API is not available in the client library
See also
getUserConnection()
Since
Qorus 4.0.3

◆ 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; hash keys are as in the following table

UserApi::getUserContextInfo() Return Value When Called from a Service
Key

Value

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

context_user

the current username context, if any


UserApi::getUserContextInfo() Return Value When Called from a Job
Key

Value

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

context_user

the current username context, if any


UserApi::getUserContextInfo() Return Value When Called from a Workflow
Key

Value

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)

context_user

the current username context, if any


In addition, when called from a finite state machine state, the contextual keys as above are available, plus the followng.
UserApi::getUserContextInfo() Return Value When Called from a Workflow
Key

Value

input

any input data for the current finite state machine state

Since
Qorus 4.1 added the context_user key

◆ getUserInfo()

static hash< QorusUserInfo > OMQ::UserApi::UserApi::getUserInfo ( *string  username)
static

Returns information for the given user.

Parameters
usernamethe user to query; if not given, then information for the current user context is returned
Returns
information for the given user
Exceptions
USER-ERRORthe user is not loaded
Note
This API is not available in the client library
Since
  • Qorus 5.1.20
  • Qorus 6.1 implemented support for returning the current user with no argument

◆ 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: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or 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
Note
This API is not available in the client library

◆ 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
Note
This API is not available in the client library
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
Note
This API is not available in the client library
See also

◆ invalidateToken()

static bool OMQ::UserApi::UserApi::invalidateToken ( string  token)
static

Invalidates the given token.

Parameters
tokenthe token to invalidated
Returns
True if the token was invalidated, False if the token was already invalid
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ isInternalSystemDebuggingEnabled()

static bool OMQ::UserApi::UserApi::isInternalSystemDebuggingEnabled ( )
static

returns True if internal system debugging is enabled

Note
This API is not available in the client library

◆ isJobContext()

static bool OMQ::UserApi::UserApi::isJobContext ( )
static

Returns True if the code is executing in an immediate job context, False if not.

Returns
True if the code is executing in an immediate job context, False if not
Since
Qorus 6.0

◆ isKubernetes()

static bool OMQ::UserApi::UserApi::isKubernetes ( )
static

returns True when Qorus is running under Kubernetes

Returns
True when Qorus is running under Kubernetes
Since
Qorus 5.1

◆ isServiceContext()

static bool OMQ::UserApi::UserApi::isServiceContext ( )
static

Returns True if the code is executing in an immediate service context, False if not.

Returns
True if the code is executing in an immediate service context, False if not
Since
Qorus 6.0

◆ 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

◆ isWorkflowContext()

static bool OMQ::UserApi::UserApi::isWorkflowContext ( )
static

Returns True if the code is executing in an immediate workflow context, False if not.

Returns
True if the code is executing in an immediate workflow context, False if not
Since
Qorus 6.0

◆ leaveParentFeedback()

static OMQ::UserApi::UserApi::leaveParentFeedback ( string  key,
auto  value 
)
static

leaves feedback for a parent workflow

This call is a wrapper for WorkflowApi::leaveParentFeedback(); please see that method for documentation

Exceptions
FEEDBACK-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 6.0

◆ 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()

◆ logWithLevel() [1/2]

static OMQ::UserApi::UserApi::logWithLevel ( int  level,
string  msg,
  ... 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message, arguments follow
Since
Qorus 4.1

◆ logWithLevel() [2/2]

static OMQ::UserApi::UserApi::logWithLevel ( Logger::LoggerLevel  level,
string  msg,
  ... 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message, arguments follow
Since
Qorus 6.0.19

◆ logWithLevelArgs() [1/2]

static OMQ::UserApi::UserApi::logWithLevelArgs ( int  level,
string  msg,
*softlist< auto >  args 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message
argsoptional argument to format specifiers in msg
Since
Qorus 4.1

◆ logWithLevelArgs() [2/2]

static OMQ::UserApi::UserApi::logWithLevelArgs ( Logger::LoggerLevel  level,
string  msg,
*softlist< auto >  args 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message
argsoptional argument to format specifiers in msg
Since
Qorus 6.0.19

◆ 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)

◆ 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 OMQ::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
Note
This API is not available in the client library

◆ 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 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

◆ propUpdate() [2/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

◆ 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()

◆ qorusGetPublicUrl()

static string OMQ::UserApi::UserApi::qorusGetPublicUrl ( *hash< auto >  cx)
static

Returns a string giving the remote / publicly-accessble system URL.

Parameters
cxConnection context information
Returns
a string giving the remote / publicly-accessble system URL taken from the qorus.public-url system option or the cx variable, if present, if neither are present, then this method returns the same value as qorusGetLocalUrl()
Since
Qorus 6.1

◆ 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
Note
This API is not available in the client library

◆ refreshToken() [1/2]

static OMQ::UserApi::UserApi::refreshToken ( string  token,
*int  expiry_seconds 
)
static

Refreshes the given token.

Parameters
tokenthe access token to refreshed
expiry_secondsthe new refresh interval; if not given then the original interval is used
Exceptions
INVALID-TOKENthrown if the token was already invalid
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ refreshToken() [2/2]

static OMQ::UserApi::UserApi::refreshToken ( string  token,
timeout  expiry_seconds 
)
static

Refreshes the given token.

Parameters
tokenthe access token to refreshed
expiry_secondsthe new refresh interval in seconds
Exceptions
INVALID-TOKENthrown if the token was already invalid
Note
This API is not available in the client library
Since
Qorus 5.1.1

◆ registerFsmAsObserver()

static OMQ::UserApi::UserApi::registerFsmAsObserver ( string  fsm_name,
DataProvider::Observable  observable,
string  event_id 
)
static

Registers the given Finite State Machine with the given object as an Observer.

Parameters
fsm_namethe name of the Finite State Machine to register with observable
observablethe event source object
event_idthe event ID to register with observable
Exceptions
FSM-NOT-FOUNDThe given Finite State Machine is not valid for the current interface context
Note
This API is not available in the client library
Since
Qorus 5.0

◆ 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
Note
This API is not available in the client library

◆ saveObjectInObjectCache()

static OMQ::UserApi::UserApi::saveObjectInObjectCache ( object  obj)
static

Saves the object in the object cache.

Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Note
This API is not available in the client library
Since
Qorus 4.1

◆ 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 of Qore intermediate serialized data

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 of Qore intermediate serialized data

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
Note
This API is not available in the client library
See also
set_option()

◆ skipAsyncStep()

OMQ::UserApi::UserApi::skipAsyncStep ( )
static

This method will skip the execution of an asynchronous step.

This call is a wrapper for QorusAsyncStepBase::skipAsyncStep(); please see that method for documentation

Exceptions
ASYNC-STEP-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ skipEvent()

OMQ::UserApi::UserApi::skipEvent ( )
static

skips a workflow synchronization event step

This call is a wrapper for QorusEventStepBase::skipEvent(); please see that method for documentation

Exceptions
EVENT-STEP-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ skipSubworkflow()

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

This method skips binding a workflow to a subworkflow step.

This call is a wrapper for QorusSubworkflowStepBase::skipSubworkflow(); please see that method for documentation

Exceptions
SUBWORKFLOW-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ 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 usleep()) 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

◆ startCapturingObjectsFromJava()

static OMQ::UserApi::UserApi::startCapturingObjectsFromJava ( )
static

Starts capturing Qore objects created from Java APIs in the current interface's object cache.

Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Note
This API is not available in the client library
Since
Qorus 4.1
See also
Managing the Lifecycle of Qore objects from Java

◆ startCapturingObjectsFromPython()

static OMQ::UserApi::UserApi::startCapturingObjectsFromPython ( )
static

Starts capturing Qore objects created from Python APIs in the current interface's object cache.

Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Note
This API is not available in the client library
Since
Qorus 5.0
See also
Managing the Lifecycle of Qore objects from Python

◆ stopCapturingObjectsFromJava()

static OMQ::UserApi::UserApi::stopCapturingObjectsFromJava ( )
static

Stops capturing Qore objects created from Java APIs in the current interface's object cache.

Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Note
This API is not available in the client library
Since
Qorus 4.1
See also
Managing the Lifecycle of Qore objects from Java

◆ stopCapturingObjectsFromPython()

static OMQ::UserApi::UserApi::stopCapturingObjectsFromPython ( )
static

Stops capturing Qore objects created from Python APIs in the current interface's object cache.

Exceptions
NO-INTERFACEthrown if there is no interface context; this API is only valid when called in a workflow, service, or job context
Note
This API is not available in the client library
Since
Qorus 5.0
See also
Managing the Lifecycle of Qore objects from Python

◆ submitAsyncKey()

OMQ::UserApi::UserApi::submitAsyncKey ( string  key)
static

Binds the given key to the asynchronous step.

This call is a wrapper for QorusAsyncStepBase::submitAsyncKey(); please see that method for documentation

Exceptions
ASYNC-STEP-ERRORin addition to exception thrown by the above function, this error is raised if this method is called when not in a workflow context
Since
Qorus 5.1.29

◆ 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 unblockOrder() 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

◆ 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

◆ updateDynamicOrderData()

static OMQ::UserApi::UserApi::updateDynamicOrderData ( softint  wfiid,
hash< auto >  new_data 
)
static

updates the given workflow order instance's dynamic data hash atomically

The given hash is merged to the order's dynamic data hash

Parameters
wfiidthe workflow order instance ID to update
new_datathe hash data to merge with the given order's dynamic data hash
Exceptions
UPDATE-WORKFLOW-ERRORforeign session id error
Note
This API is not available in the client library
See also
updateDynamicOrderDataPath()
Since
Qorus 5.1.10

◆ updateDynamicOrderDataPath()

static OMQ::UserApi::UserApi::updateDynamicOrderDataPath ( softint  wfiid,
string  path,
auto  value 
)
static

updates the given workflow order instance's dynamic data hash atomically

The given value is written to the path provided in the workflow order instance's dynamic data hash

Parameters
wfiidthe workflow order instance ID to update
paththe dotted path to the value to update
valuethe value to update in the location provided by path
Exceptions
UPDATE-WORKFLOW-ERRORforeign session id error
Note
This API is not available in the client library
See also
updateDynamicOrderData()
Since
Qorus 5.1.10

◆ 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 ( hash< auto >  all_output_data,
hash< auto >  output_data_cfg = UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY, NOTHING, False) 
)
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}"});
# write the account ID in the "account" hash to the account -> id field in dynamic data
UserApi::updateOutputData({"account": {"account_id": account_id}}, {"account.account_id": "$dynamic:{account.id}"});
# write the entire output hash (first argument) to the location provided by the value in the second argument
UserApi::updateOutputData(row_data, {"*": "$dynamic:{account.info}"});
# write the entire output account hash (first argument) to the location provided by the value in the second argument
# and ignore the error if the account information is missing
UserApi::updateOutputData(row_data, {"account?.*": "$dynamic:{account.info}"});
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 this hash (other than "*") must also be present in all_output_data; 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; note special key "*" which indicates that the entire all_output_data hash should be written to the output location; note that this value also accepts hash paths such as "key1.key2.key3"; if a key contains a "." character, you must escape it with backslashes (ex: "key\.with\.dots"); additionally, this method will throw an exception if any element in the hash does not resolve to a value; to ignore the situation when data is missing, append a "?" to the key name; ex: "key1.optional_key?.final_key" or "key2.key3.final_key?"; in this case missing data is ignored and no exception is thrown.

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 (without a "?" appended to the 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
Note
If the output data is retrieved from a configuration item, it is not subject to recursive expansion
See also
Since
  • Qorus 4.0.3
  • Qorus 5.1.6 introduced the special key "*" in output_data_cfg, indicating that the entire output hash (all_output_data) should be written to the output location provided as the value to this key
  • Qorus 5.1.7 implemented output path following and optional fields in all_output_data to suppress the OUTPUT-CONFIG-ERROR exception in case of missing data

◆ updateOutputData() [2/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
See also
writeOutputData()
Since
Qorus 4.0.3

◆ usleep() [1/2]

static int OMQ::UserApi::UserApi::usleep ( date  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

◆ usleep() [2/2]

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

◆ writeFileToLocation()

static OMQ::UserApi::UserApi::writeFileToLocation ( string  location,
data  contents 
)
static

Writes data to a file at the given location.

Parameters
locationthe location of the file data
contentsthe file contents to write to the location
Since
Qorus 5.1.24

◆ writeOutputData()

static OMQ::UserApi::UserApi::writeOutputData ( *hash< auto >  output_data)
static

Writes output data using a concise format.

Example
# write the the input of FSM state data to the "account" key of the current workflow order's dynamic data hash
UserApi::writeOutputData({"$local:input": "$dynamic:account"});
Parameters
output_dataa hash of output data; keys are template strings to be resolved to values; values are locations to write the data to; no value or an empty hash means the call is ignored
Note
local input data is made up of the results of getUserContextInfo(); note that the "input" key in this hash is set to any current input data when running in a finite state machine
See also
updateOutputData()
Since
Qorus 5.1.29

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