Qorus Integration Engine®  4.0.3.p2_git
OMQ::UserApi::Job::JobApi Class Reference

primary job API class More...

Inheritance diagram for OMQ::UserApi::Job::JobApi:
OMQ::UserApi::UserApi

Static Public Member Methods

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

Detailed Description

primary job API class

Member Function Documentation

◆ err()

static OMQ::UserApi::Job::JobApi::err ( string  err,
string  desc_fmt 
)
static

raises an error in a running job; does not affect the flow of execution in the job code

the error information is stored in the job_errors table with a severity of OMQ::ES_Major and the business flag set to True

Parameters
errthe error code
desc_fmtthe format specifier for the warning description string; following arguments will be included in the description string as combined with vsprintf()
Since
Qorus 3.1.0
See also

◆ errWithInfo()

static OMQ::UserApi::Job::JobApi::errWithInfo ( string  err,
softstring  desc = "",
auto  info,
softstring  severity = OMQ::ES_Major,
softbool  business = False 
)
static

raises an error in a running job; does not affect the flow of execution in the job code

the error information is stored to the job_errors table, errors errors with a severity less than or equal to OMQ::ES_Warning are treated as warnings

Parameters
errthe error code
desca description for the error
infoadditional information to be saved with the error (data structures are serialized in YAML format and saved in the database)
severitythe severity of the error, errors with a severity less than or equal to OMQ::ES_Warning are treated as warnings; see Error Severity Codes for valid values (default = OMQ::ES_Major)
businessset to True if the error represents a business error
Note
If the severity is less than or equal to OMQ::ES_Warning, the job instance does not get an OMQ::JS_Error status
See also

◆ getConfigItemHash()

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

returns a hash of all configuration items for the current job

Example:
hash<auto> config = JobApi::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 job; keys are config item names; values are config item values. If there are no config items for the current job, 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
values are always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
See also
Class-Based Job Configuration Items

◆ getConfigItemValue()

static auto OMQ::UserApi::Job::JobApi::getConfigItemValue ( string  item,
*hash< auto >  local_context 
)
static

returns the value of the given job configuration item

Example:
auto val = JobApi::getConfigItemValue(item);
Parameters
itemthe name of the job configuration item; job configuration item values take precedence over values on global level if both are set otherwise if both are not set the default value is returned
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
the value of the given configuration item
Note
values are always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
See also
Class-Based Job Configuration Items

◆ getInfo()

static hash<auto> OMQ::UserApi::Job::JobApi::getInfo ( )
static

returns a hash of job information about the current job

Returns
a hash with the following keys:
  • jobid: the metadata jobid of the job type
  • job_instanceid: the id of the job instance
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • last_executed: the last executed date/time of the job (NOTHING if never executed before the current iteration)
  • last_executed_job_instanceid: the last executed instance id of the job
  • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
  • next: the next trigger date/time
Note
the data returned here is different from the data stored by job_save_info()
See also

◆ getOption()

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

Returns the value of the named job option(s)

If the option is not set on the job level, 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 no arguments are passed to the method all job-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getOptionArgs()

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

Returns the value of the named job option or options.

If the option is not set on the job, 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 no arguments are passed to the method all job-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getStateData()

static *hash<auto> OMQ::UserApi::Job::JobApi::getStateData ( )
static

returns any job state state data stored with job_save_state_data()

Returns
any job state state data stored with job_save_state_data()
Note
job state state data is automatically cleared when a job instance gets a OMQ::StatComplete status
See also

◆ saveInfo()

static OMQ::UserApi::Job::JobApi::saveInfo ( auto  info)
static

saves information against the job instance in the database

The information is serialized in YAML format and saved in the database in the JOB_INSTANCE row as a part of the job results.

This information is returned in the API as the info key in REST Job Result Hash data, for example in the return value to the REST GET /api/latest/jobresults/{id} call.

Parameters
infothe information to save
Note
the data stored here is different from the data returned by job_info()
See also

◆ saveStateData()

static OMQ::UserApi::Job::JobApi::saveStateData ( hash< auto >  data)
static

serializes the given hash and stores against the job's state data in JOB_STATE_DATA

Parameters
datathe state data to serialize and store against the job's state data in JOB_STATE_DATA
Note
job state state data is automatically cleared when a job instance gets a OMQ::StatComplete status
See also

◆ setOption() [1/2]

static OMQ::UserApi::Job::JobApi::setOption ( hash< auto >  opts)
static

Changes option values on a job.

If at least one 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
optsa hash of option-value pairs
Exceptions
JOB-OPTION-ERRORinvalid option name
See also

◆ setOption() [2/2]

static OMQ::UserApi::Job::JobApi::setOption ( string  option,
auto  value 
)
static

Changes a single option value on a job.

If an invalid option is passed to the method, an exception will be raised.

Parameters
optionthe option to set
valuethe value to set for the option
Exceptions
JOB-OPTION-ERRORinvalid option name
See also

◆ setTrigger()

static bool OMQ::UserApi::Job::JobApi::setTrigger ( date  ts)
static

sets a one-time custom trigger time for the job; returns True if set, False if ignored

Parameters
tsthe timestamp to trigger the job; must be in the future and before the next trigger time
Returns
True if set, False if ignored; the call will be ignored if the date/time value is in the past or after the next scheduled job trigger time
Note
when this API returns with a True return value, the job's custom trigger time has already been committed to the database
See also
job_set_trigger()

◆ sleep()

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

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

If the job 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

◆ usleep() [1/2]

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

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

If the job 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::Job::JobApi::usleep ( date  arg)
static

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

If the job 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 amount of time in 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

◆ warn()

static OMQ::UserApi::Job::JobApi::warn ( string  err,
string  desc_fmt 
)
static

raises a warning in a running job; does not affect the flow of execution in the job code

the warning information is stored to the job_errors table with a severity of OMQ::ES_Warning and the business flag set to True

Parameters
errthe warning or error code
desc_fmtthe format specifier for the warning description string; following arguments will be included in the description string as combined with vsprintf()
See also

◆ warnWithInfo()

static OMQ::UserApi::Job::JobApi::warnWithInfo ( string  err,
softstring  desc = "",
auto  info,
softbool  business = False 
)
static

raises a warning in a running job; does not affect the flow of execution in the job code

the warning information is stored to the job_errors table with a severity of OMQ::ES_Warning

Parameters
errthe warning or error code
desca description for the warning
infoadditional information to be saved with the warning (data structures are serialized in YAML format and saved in the database)
businessset to True if the warning represents a business warning
See also

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