Qorus Integration Engine®  4.0.3.p1_git
QorusSystemAPI.qc File Reference

defines the Qorus System API methods More...

Functions

hash omq.system.help ()
 gives a hash of API information, where each key is a Qorus system API method More...
 
hash omq.system.get-option-info ()
 returns a hash of all global Qorus system options and their current values More...
 
hash omq.system.get-status ()
 returns a hash giving information about system status More...
 
string omq.system.set-option (hash params)
 sets one or more system options More...
 
string omq.system.flush-options (*hash params)
 write the server's options to the option file on the server's filesystem More...
 
string omq.system.shutdown ()
 initiates the system shutdown process More...
 
string omq.system.shutdown-wait ()
 shuts down the system; returns when the system shutdown process is complete More...
 
hash omq.system.submit-data.[workflow].[version] (hash params, string status=OMQ::StatReady)
 create workflow order (workflow order data instance) More...
 
hash omq.system.create-order (hash params)
 create workflow order method (workflow order data instance) More...
 
any omq.system.get-workflow-info (*softstring id)
 returns workflow information for the execution id passed, or for all workflows if no execution id is passed More...
 
list omq.system.show-workflow-cache ()
 returns a list of the workflows currently cached More...
 
hash omq.system.start-workflow (hash params)
 Starts a workflow execution instance with the designated name and version. More...
 
hash omq.system.start-workflows (hash params)
 Starts one or more workflow execution instances with the designated name and version. More...
 
hash omq.system.exec-synchronous-workflow (hash params)
 Executes a workflow in synchronous mode and returns the final status of the order after processing. More...
 
hash omq.system.exec-synchronous-existing (hash params)
 Executes a workflow in synchronous mode against an already-existing order in the database with status OMQ::StatReady. More...
 
string omq.system.stop-all-workflows ()
 stops all running workflows More...
 
string omq.system.stop-workflow-instance (softint id)
 stops the given workflow execution instance given its ID More...
 
string omq.system.stop-workflow (string name, *string version)
 stops all instances of the given workflow More...
 
string omq.system.set-workflow-option (softint id, hash hash)
 Sets the options given in the hash on the running workflow identified by the execution ID passed. More...
 
any omq.system.get-workflow-option (softint id)
 Returns options set on the running workflow identified by the execution ID passed. More...
 
hash omq.system.get-workflow-options (softint id)
 Returns all options set on the running workflow identified by the execution ID passed. More...
 
string omq.system.reset-workflow (string name, *string version)
 Deletes the configuration for the specified workflow from the cache. More...
 
string omq.system.reset-all-workflows ()
 Deletes the configuration for all workflows from the workflow configuration cache. More...
 
string omq.system.replace-dynamic-data (softstring wfiid, *hash data)
 Replaces the dynamic data for the given workflow order data instance. More...
 
string omq.system.replace-static-data (softstring wfiid, *hash data)
 Replaces the static data for the given workflow order data instance. More...
 
hash omq.system.retry-workflow-instance (softstring wfiid)
 retries the given workflow order instance More...
 
hash omq.system.retry-workflow-instances (softlist l)
 retries the given workflow order instances More...
 
hash omq.system.cancel-workflow-instance (softint wfiid, any cancel)
 cancels the given workflow order data instance or resets a canceled order to the original status More...
 
hash omq.system.cancel-workflow-instances (hash ih)
 cancels the given workflow order data instance or resets a canceled order to the original status More...
 
string omq.system.reschedule-order (softint wfiid, *softdate scheduled)
 sets or removes the scheduled date for a workflow order data instance More...
 
hash omq.system.reschedule-orders (hash ih)
 sets or removes the scheduled date for a list of workflow order data instances More...
 
string omq.system.reprioritize-order (softint wfiid, softint priority)
 changes the priority for an existing workflow order data instance More...
 
hash omq.system.reprioritize-orders (hash ih)
 changes the priority for a list of workflow order data instances More...
 
hash omq.system.block-workflow-instance (softint wfiid, any block)
 block the given workflow order data instance or resets a blocked order to the original status More...
 
hash omq.system.block-workflow-instances (hash ih)
 block or restore the list of workflow order data instances More...
 
hash omq.system.set-workflow-instance-error (softint wfiid)
 Changes a workflow order data instance's status to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting. More...
 
hash omq.system.set-workflow-instances-error (softlist l)
 Changes a list of workflow order data instances' statuses to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting. More...
 
nothing omq.system.skip-step (softstring wfiid, softstring stepid, softint ind=0)
 Skips execution of a step in a workflow. More...
 
nothing omq.system.skip-step-without-retry (softint wfiid, softint stepid, softint ind=0)
 Skips execution of a step in a workflow without initiating an immediate retry. More...
 
nothing omq.system.set-order-info (softstring wfiid, hash h)
 Sets or clears additional info for the given workflow order data instance. More...
 
hash omq.system.get-order-info (softstring wfiid)
 Gets additional info for the given workflow order data instance. More...
 
nothing omq.system.set-order-note (softstring wfiid, string notestr)
 Add new Order Instance Notes. More...
 
list omq.system.order-notes (softstring wfiid, *softint count)
 Gets Order Instance Notes. More...
 
nothing omq.system.post-event (softstring eventtype, softstring eventkey)
 Posts a workflow synchronization event with the event type name and key value. More...
 
hash omq.system.runtime-properties ()
 Returns a hash with runtime properties specified with -D in the Qorus system startup command-line. More...
 
any omq.system.list-all-services (*date date)
 returns a list of all services currently loaded or a constant string if the services have not been updated since the optional date argument More...
 
list omq.system.list-services ()
 returns a list of all system services currently loaded More...
 
list omq.system.reset-all-services ()
 unloads all services currently loaded in memory and reloads them from the database More...
 
list omq.system.reset-services ()
 unloads all system services currently loaded in memory and reloads them from the database More...
 
bool omq.system.reset-service (string name, bool load=False)
 unloads a single system service and reloads it from the database More...
 
any omq.system.service.[servicename].[method] ()
 calls a system service method and returns the result More...
 
string omq.system.delete-service (string name, *string version)
 Unloads the named system service from the system. More...
 
string omq.system.set-service-autostart (string name, softstring stat)
 Sets the autostart status of the given system service. More...
 
bool omq.system.get-service-autostart (string name)
 returns the autostart status of the given system service More...
 
string omq.system.set-service-options (string name, hash hash)
 Sets the options given in the hash on the given service. More...
 
any omq.system.get-service-options (string name)
 Returns options set on the given system service; the service must be already loaded or an exception is raised. More...
 
list omq.user.list-services ()
 returns a list of all user services currently loaded More...
 
list omq.user.reset-services ()
 unloads all user services currently loaded in memory and reloads those services from the database More...
 
bool omq.user.reset-service (string name, bool load=False)
 unloads a single user service and reloads it from the database More...
 
any omq.user.service.[servicename].[method] ()
 calls a user service method and returns the result More...
 
string omq.user.delete-service (string name, *string version)
 Unloads the named user service from the system. More...
 
string omq.user.set-service-autostart (string name, softstring stat)
 Sets the autostart status of the given user service. More...
 
bool omq.user.get-service-autostart (string name)
 returns the autostart status of the given user service More...
 
string omq.user.set-service-options (string name, hash hash)
 Sets the options given in the hash on the given service. More...
 
any omq.user.get-service-options (string name)
 Returns options set on the given unsert service; the service must be already loaded or an exception is raised. More...
 
string omq.system.reload-rbac ()
 Reloads the all RBAC information (users, permissions, roles, groups) from the system schema. More...
 
string omq.system.add-user (string user, string pass, string name, *softlist roles)
 Adds a user to the system; also creates the user in the database. More...
 
string omq.system.update-user (string user, hash hash)
 Modifies an existing user in the database and in the RBAC cache. More...
 
string omq.system.passwd (softstring oldpwd, softstring newpwd)
 Changes the password for the current user. More...
 
string omq.system.delete-user (string user)
 Deletes an existing user from the database and the RBAC cache. More...
 
string omq.system.add-role (string name, string desc, *softlist permissions, softlist groups=list("DEFAULT"))
 Permanently add a role to the system. More...
 
string omq.system.clone-role (string source_role, string new_role, string desc)
 Permanently add a role to the system by cloning an existing role's permissions and groups. More...
 
string omq.system.update-role (string name, hash h)
 Modifies an existing role in the database and in the RBAC cache. More...
 
string omq.system.delete-role (string role)
 Deletes an existing role from the database and the RBAC cache. More...
 
string omq.system.add-permission (string permission, string desc)
 Permanently add a user permission to the system. More...
 
string omq.system.update-permission (string permission, string desc)
 Modifies the description for an existing user permission in the database and in the RBAC cache. More...
 
string omq.system.delete-permission (string permission)
 Deletes an existing user permission from the database and the RBAC cache. More...
 
hash omq.system.get-all-users ()
 Returns a hash with all information (except passwords) on all Qorus users in the RBAC cache. More...
 
hash omq.system.get-all-roles ()
 Returns a hash with information on all roles in the RBAC cache. More...
 
hash omq.system.get-all-permissions ()
 returns a hash of information about all permissions in the RBAC cache More...
 
string omq.system.update-current-user (hash hash)
 Modifies the current user in the database and in the RBAC cache. More...
 
hash omq.system.get-current-user-info ()
 Returns a hash with all information (except passwords) on for the current user from the RBAC cache. More...
 
hash omq.system.get-user-info (*string user)
 Returns a hash with all information (except passwords) on for the given or current user from the RBAC cache. More...
 
hash omq.system.get-role-info (string role)
 Returns a hash with information on all roles in the RBAC cache. More...
 
string omq.system.rotate-log-files ()
 Rotates all system log files. More...
 
string omq.system.ping ()
 Returns a constant "OK" string. More...
 
string omq.system.authenticate ()
 returns a constant string "admin" More...
 
hash omq.system.wait-for-events (softint min_id, *timeout timeout_ms)
 Returns a hash giving the list of the new events and the last event ID generated by the system. More...
 
hash omq.system.wait-for-events-or (softint min_id, *softlist criteria, *timeout timeout_ms, *softlist and_not, *softlist nfilt)
 return system events that meet any of the given criteria and none of the optional "and not" criteria More...
 
hash omq.system.wait-for-events-and (softint min_id, *softlist criteria, *timeout timeout_ms, *softlist or_not, *softlist nfilt)
 return system events that meet all of the given criteria or none of the optional "or not" criteria More...
 
int omq.system.get-last-event-id ()
 returns the last system event ID generated More...
 
hash omq.system.get-last-events (softint count)
 returns the last system events More...
 
hash omq.system.get-last-events-or (softint count, *softlist filter, *softlist and_not, *softlist nfilt)
 gets the last system events that meet any of the filter criteria and none of the "and_not" criteria, if present More...
 
hash omq.system.get-last-events-and (softint count, *softlist filter, *softlist or_not, *softlist nfilt)
 gets the last system events that meet all of the filter criteria or none of the "or_not" criteria, if present More...
 
hash omq.system.get-listeners ()
 returns a hash of listener information for the HTTP server More...
 
nothing omq.system.stop-listener (softstring name)
 stops the listener from the bind address More...
 
nothing omq.system.stop-listener-id (softint id)
 stops the listener from listener ID More...
 
list omq.system.start-listeners (softstring bind, *string cert_file, *string key_file)
 starts a new HTTP listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given More...
 
nothing omq.system.group.set-status (string name, softstring enabled)
 Enables or disables an interface group. More...
 
int omq.system.group.create (string name, string desc, softlist svcids, softlist wfids, softstring enabled=True, softlist jobids=(), softlist mapperids=(), softlist vmapids=())
 Creates an interface group. More...
 
string omq.system.group.update (string group, hash hash)
 Modifies an existing interface group in the database and in the RBAC cache. More...
 
nothing omq.system.group.delete (string name)
 Permanently deletes a workflow/service/job group. More...
 
nothing omq.system.group.add-workflow (string name, string wname, *string ver)
 Adds a workflow to a workflow/service/job group from the workflow's name and optional version. More...
 
nothing omq.system.group.add-service (string name, string sname, *string ver)
 Adds a service to a workflow/service/job group from the service's name and optional version. More...
 
nothing omq.system.group.add-job (string name, string jname)
 Adds a job to a workflow/service/job group from the job's name. More...
 
nothing omq.system.group.add-workflow-id (string name, softlist ids)
 Adds one or more workflows to a workflow/service/job group from the workflowids. More...
 
nothing omq.system.group.add-service-id (string name, softlist ids)
 Adds one or more services to a workflow/service/job group from the serviceids. More...
 
nothing omq.system.group.add-job-id (string name, softlist ids)
 Adds one or more jobs to a workflow/service/job group from the jobids. More...
 
nothing omq.system.group.delete-workflow (string name, string wname, *string ver)
 Permanently deletes a workflow from a workflow/service/job group using the workflow's name and optional version. More...
 
nothing omq.system.group.delete-service (string name, string sname, *string ver)
 Permanently deletes a service from a workflow/service/job group using the service's name and optional version. More...
 
nothing omq.system.group.delete-job (string name, string jname)
 Permanently deletes a job from an interface group using the job's name. More...
 
nothing omq.system.group.delete-workflow-id (string name, softlist ids)
 Permanently deletes one or more workflows from a workflow/service/job group using workflow ids. More...
 
nothing omq.system.group.delete-service-id (string name, softlist ids)
 Permanently deletes one or more services to a workflow/service/job group from the service ids. More...
 
nothing omq.system.group.delete-job-id (string name, softlist ids)
 Permanently deletes one or more jobs from an interface group using job ids. More...
 
hash omq.system.group.info (*string name)
 Returns information for a group or all groups if no group name argument is passed. More...
 
hash omq.system.job.info (*string name)
 Returns information on all jobs visible to the calling user or a specific job depending on the argument (or lack thereof) More...
 
hash omq.system.job.info-id (softint id)
 Returns information on a specific job by the jobid. More...
 
hash omq.system.job.list-active ()
 Returns information on all active jobs visible to the calling user. More...
 
hash omq.system.job.run (string name)
 Runs the given job immediately (regardless of the trigger time) from the job name even if the job is expired, inactive, or dedicated to another instance. More...
 
hash omq.system.job.run-id (softint id)
 Runs the given job immediately (regardless of the trigger time) from the jobid even if the job is expired, inactive, or dedicated to another instance. More...
 
string omq.system.job.set-active (string name, *softstring active)
 Updates the "active" status of a job from the job name; if any errors occur an exception is thrown. More...
 
string omq.system.job.set-active-id (softint id, *softstring active)
 Updates the "active" status of a job from the job id; if any errors occur an exception is thrown. More...
 
string omq.system.job.set-expiry (string name, *date expiry)
 Updates the expiry date of a job from the job name; if any errors occur an exception is thrown. More...
 
string omq.system.job.set-expiry-id (softint id, *date expiry)
 Updates the expiry date of a job from the job id; if any errors occur an exception is thrown. More...
 
string omq.system.job.schedule (string name, *string schedule, *softint recurring)
 Updates a job's schedule from the job name; if any errors occur an exception is thrown. More...
 
string omq.system.job.schedule-id (softint id, *string schedule, *softint recurring)
 Updates a job's schedule from the jobid; if any errors occur an exception is thrown. More...
 
string omq.system.job.reset (string name)
 Reloads a job from the database from its name; if it's currently running it is stopped and reloaded. More...
 
string omq.system.job.reset-id (softint id)
 Reloads a job from the database from its id; if it's currently running it is stopped and reloaded. More...
 
string omq.system.job.reset-all ()
 Reloads all jobs from the database; all currently-running jobs are stopped and reloaded. More...
 
string omq.system.job.set-options (string name, hash hash)
 Sets the options given in the hash on the given job; the job must be active or an exception is raised. More...
 
any omq.system.job.get-options (string name)
 Returns options set on the given job; the job must be active or an exception is raised. More...
 
string omq.system.job.set-options-id (softint id, hash hash)
 Sets the options given in the hash on the given job; the job must be active or an exception is raised. More...
 
any omq.system.job.get-options-id (softint id)
 Returns options set on the given job; the job must be active or an exception is raised. More...
 
hash omq.system.schema.refresh-snapshots ()
 Refresh helper database snapshots. More...
 
*hash omq.system.get-global-errors (*softlist l)
 returns global error definition information More...
 
*hash omq.system.get-workflow-errors (softint wfid, *softlist l)
 returns workflow-specific error definition information More...
 
hash omq.system.get-all-errors ()
 returns all global and workflow-specific error definitions More...
 
*hash omq.system.search-errors (softlist l)
 searches for error definitions at all levels for the given error(s) More...
 
string omq.system.update-global-error (hash eh)
 creates or updates a global error More...
 
string omq.system.update-workflow-error (softint wfid, hash eh, *bool forceworkflow)
 creates or updates a workflow-specific error definition More...
 
bool omq.system.delete-workflow-error (softint wfid, string err)
 deletes a workflow-specific error so that the global error definition will be used instead More...
 
int omq.system.delete-error (string err)
 deletes all definitions of an error from all workflows and at the global level More...
 
hash omq.system.reload-errors ()
 reloads all error definitions from the DB More...
 
any omq.system.debug.echo ()
 echos any argument passed More...
 
hash omq.system.debug.get-thread-stacks ()
 returns information about the status of running threads More...
 
string omq.system.debug.get-data-cache ()
 returns detailed technical data about the workflow order data cache for debugging purposes More...
 
string omq.system.debug.get-data-cache-summary ()
 returns summarized technical data about the workflow order data cache for debugging purposes More...
 
string omq.system.debug.get-segment-cache ()
 returns detailed technical data about the segment event cache for debugging purposes More...
 
string omq.system.debug.get-segment-summary ()
 returns summarized technical data about the segment event cache for debugging purposes More...
 
string omq.system.debug.get-workflow-queue-status ()
 returns a description of the workflow queue thread pool More...
 
hash omq.system.debug.get-mon ()
 returns a description of internal monitoring data structures More...
 
string omq.system.debug.dump-caches ()
 returns technical data about the segment cache for debugging purposes More...
 
string omq.system.debug.dump-system-pool ()
 returns a description of the status of the system DatasourcePool More...
 
string omq.system.debug.dump-exec-cache ()
 returns technical data about the execution cache for debugging purposes More...
 
string omq.system.debug.get-workflow-entry (softint wfiid)
 returns technical cache data about an internal workflow entry for debugging purposes More...
 
nothing omq.system.debug.workflow-entry (softint wfiid, *string flag)
 sets the debug flag on a cached workflow entry for debugging purposes More...
 
nothing omq.system.debug.system (softstring flag)
 turns system debugging on or off More...
 

Detailed Description

defines the Qorus System API methods

Function Documentation

◆ omq.system.add-permission()

string omq.system.add-permission ( string  permission,
string  desc 
)

Permanently add a user permission to the system.

Also creates the user permission in the database

Parameters
permissionthe name of the permission to add
descthe description of the permission
Returns
"OK"
Exceptions
RBAC-ADD-PERMISSION-ERRORinvalid permission (permission already exists)
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_PERMISSION

◆ omq.system.add-role()

string omq.system.add-role ( string  name,
string  desc,
*softlist  permissions,
softlist  groups = list("DEFAULT") 
)

Permanently add a role to the system.

Also creates the role in the database

Parameters
namethe name of the role to add
descthe description of the role
permissionsa single permission or a list of permissions to add to the role; note that users must have at least the OMQ::QR_LOGIN permission to connect to the server
groupsa single group or a list of groups to add to the role
Returns
"OK"
Exceptions
RBAC-ADD-ROLE-ERRORinvalid role (already exists), invalid permission, invalid group
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_ROLE

◆ omq.system.add-user()

string omq.system.add-user ( string  user,
string  pass,
string  name,
*softlist  roles 
)

Adds a user to the system; also creates the user in the database.

Parameters
userthe username to add
passthe password for the user
namethe name of the user
rolesa single role or a list of roles to add to the user; note that the user must have at least the OMQ::QR_LOGIN permission to connect to the server
Returns
"OK"
Exceptions
RBAC-ADD-USER-ERRORinvalid user, invalid role, invalid group
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_USER

◆ omq.system.authenticate()

string omq.system.authenticate ( )

returns a constant string "admin"

Deprecated:
This function is present for backwards-compatibility and no longer performs any useful function now that the RBAC framework is in place
Returns
"admin"

◆ omq.system.block-workflow-instance()

hash omq.system.block-workflow-instance ( softint  wfiid,
any  block 
)

block the given workflow order data instance or resets a blocked order to the original status

If the block argument set to True (or missing) it changes a workflow order data instance's status to OMQ::StatBlocked. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatBlocked status (unless the workflow instance is recovered back from OMQ::StatBlocked or the status is first updated to OMQ::StatError and then to OMQ::StatRetry). If the blocked argument is set to False the workflow instance is recovered back to its original status and it is processed.

Parameters
wfiidthe workflow order data instance ID
blockif missing or evaluates to True, then the order is blocked, if False then the order is unblocked
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, unblock operation already in progress
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
See also
omq.system.block-workflow-instances()
Since
Qorus 2.5.0

◆ omq.system.block-workflow-instances()

hash omq.system.block-workflow-instances ( hash  ih)

block or restore the list of workflow order data instances

If the block argument is set to True it changes a workflow order data instance's status to OMQ::StatBlocked, otherwise orders with a OMQ::StatBlocked status are restored to their original status. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatBlocked status (unless the workflow instance is recovered back from OMQ::StatBlocked or the status is first updated to OMQ::StatError and then to OMQ::StatRetry). If the blocked argument is set to False the workflow instance is recovered back to its original status and it is processed.

Parameters
iha hash where each key is the workflow_instanceid to block or unblock, and the value is the block status (boolean True means block or False means unblock)
Returns
a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or a hash with the following key:
  • workflow_status: the status of the workflow order
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_BLOCK_WORKFLOW_ORDER
Since
Qorus 2.5.1.p7
See also
omq.system.block-workflow-instance()

◆ omq.system.cancel-workflow-instance()

hash omq.system.cancel-workflow-instance ( softint  wfiid,
any  cancel 
)

cancels the given workflow order data instance or resets a canceled order to the original status

If the cancel argument is True (or missing) it changes a workflow order data instance's status to OMQ::StatCanceled. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatCanceled status (unless the workflow instance is recovered back from OMQ::StatCanceled or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).

Parameters
wfiidthe workflow_instanceid of the order to process
cancelif set to False the workflow instance is recovered back to its original status and it is processed, otherwise if True or missing then the order is canceled
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
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
See also
omq.system.cancel-workflow-instances()

◆ omq.system.cancel-workflow-instances()

hash omq.system.cancel-workflow-instances ( hash  ih)

cancels the given workflow order data instance or resets a canceled order to the original status

If the cancel argument is set to True (or missing) it changes a workflow order data instance's status to OMQ::StatCanceled. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatCanceled status (unless the workflow instance is recovered back from OMQ::StatCanceled or the status is first updated to OMQ::StatError and then to OMQ::StatRetry). If the cancel argument is set to False the workflow instance is recovered back to its original status and it is processed.

Parameters
iha hash where each key is the workflow_instanceid to cancel or uncancel, and the value is the cancel status (boolean True means cancel or False means uncancel)
Returns
a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or 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
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_CANCEL_WORKFLOW_ORDER
See also
omq.system.cancel-workflow-instance()
Since
Qorus 2.5.1.p7

◆ omq.system.clone-role()

string omq.system.clone-role ( string  source_role,
string  new_role,
string  desc 
)

Permanently add a role to the system by cloning an existing role's permissions and groups.

Also creates the role in the database

Parameters
source_rolethe name of the source role
new_rolethe name of the role to add
descthe description of the role
Returns
"OK"
Exceptions
RBAC-ADD-ROLE-ERRORinvalid role (already exists), invalid permission, invalid group
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_ROLE
Since
Qorus 3.0

◆ omq.system.create-order()

hash omq.system.create-order ( hash  params)

create workflow order method (workflow order data instance)

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

Parameters
paramsThe hash passed must have at either a staticdata key or an external_order_instanceid key, valid keys:
  • name: the name of the workflow to create
  • [version]: the version of the workflow to create; if this is omitted, then the latest version of the workflow is used
  • [staticdata]: the static data for the order; either this key or external_order_instanceid is required
  • [external_order_instanceid]: the external order instance ID for the workflow data; either this key or staticdata is required
  • [dynamicdata]: the initial dynamic data for the order
  • [orderkeys]: a hash of order keys for the order
  • [scheduled]: 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
  • [priority]: the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • [status]: the initial order status (default OMQ::StatReady); must be either OMQ::StatReady or OMQ::StatBlocked
  • [parent_workflow_instanceid]: a loosely-coupled workflow that will be marked as the parent of this workflow
Returns
a hash with the following key:
  • workflow_instanceid the workflow instance ID of the workflow order instance ID created
Exceptions
SUBMIT-ORDER-ERRORunknown workflow, invalid status
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SUBMIT_ORDER

◆ omq.system.debug.dump-caches()

string omq.system.debug.dump-caches ( )

returns technical data about the segment cache for debugging purposes

Returns
technical data about the segment cache for debugging purposes

◆ omq.system.debug.dump-exec-cache()

string omq.system.debug.dump-exec-cache ( )

returns technical data about the execution cache for debugging purposes

Returns
technical data about the execution cache for debugging purposes

◆ omq.system.debug.dump-system-pool()

string omq.system.debug.dump-system-pool ( )

returns a description of the status of the system DatasourcePool

Returns
a description of the status of the system DatasourcePool

◆ omq.system.debug.echo()

any omq.system.debug.echo ( )

echos any argument passed

Returns
echos any argument passed

◆ omq.system.debug.get-data-cache()

string omq.system.debug.get-data-cache ( )

returns detailed technical data about the workflow order data cache for debugging purposes

Returns
detailed technical data about the workflow order data cache for debugging purposes

◆ omq.system.debug.get-data-cache-summary()

string omq.system.debug.get-data-cache-summary ( )

returns summarized technical data about the workflow order data cache for debugging purposes

Returns
summarized technical data about the workflow order data cache for debugging purposes

◆ omq.system.debug.get-mon()

hash omq.system.debug.get-mon ( )

returns a description of internal monitoring data structures

Returns
a description of internal monitoring data structures

◆ omq.system.debug.get-segment-cache()

string omq.system.debug.get-segment-cache ( )

returns detailed technical data about the segment event cache for debugging purposes

Returns
detailed technical data about the segment event cache for debugging purposes

◆ omq.system.debug.get-segment-summary()

string omq.system.debug.get-segment-summary ( )

returns summarized technical data about the segment event cache for debugging purposes

Returns
summarized technical data about the segment event cache for debugging purposes

◆ omq.system.debug.get-thread-stacks()

hash omq.system.debug.get-thread-stacks ( )

returns information about the status of running threads

Returns
information about the status of running threads

◆ omq.system.debug.get-workflow-entry()

string omq.system.debug.get-workflow-entry ( softint  wfiid)

returns technical cache data about an internal workflow entry for debugging purposes

Returns
technical cache data about an internal workflow entry for debugging purposes

◆ omq.system.debug.get-workflow-queue-status()

string omq.system.debug.get-workflow-queue-status ( )

returns a description of the workflow queue thread pool

Returns
a description of the workflow queue thread pool

◆ omq.system.debug.system()

nothing omq.system.debug.system ( softstring  flag)

turns system debugging on or off

Parameters
flagturns system debugging on or off

◆ omq.system.debug.workflow-entry()

nothing omq.system.debug.workflow-entry ( softint  wfiid,
*string  flag 
)

sets the debug flag on a cached workflow entry for debugging purposes

Returns
nothing

◆ omq.system.delete-error()

int omq.system.delete-error ( string  err)

deletes all definitions of an error from all workflows and at the global level

Changes are committed internally and also to the database in this method (i.e. all changes are persistent)

Parameters
errthe name of the error to delete
Returns
a count of all error definition instances deleted
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access at least one of the affected workflows (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
Since
Qorus 2.8.0

◆ omq.system.delete-permission()

string omq.system.delete-permission ( string  permission)

Deletes an existing user permission from the database and the RBAC cache.

System permissions may not be deleted; only user permissions may be deleted.

This operation will fail if the permission is currently associated to any roles. To remove a permission that is associated with one or more roles, first remove the permission from all roles and then remove the permission, or use the user-tool program to perform a cascading delete of the permission and synchronize the RBAC cache with the database by calling Qorus API function omq.system.reload-rbac().

Parameters
permissionthe permission to delete
Returns
"OK"
Exceptions
RBAC-DELETE-PERMISSION-ERRORinvalid permission
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_DELETE_PERMISSION

◆ omq.system.delete-role()

string omq.system.delete-role ( string  role)

Deletes an existing role from the database and the RBAC cache.

Parameters
rolethe role to delete
Returns
"OK"
Exceptions
RBAC-DELETE-ROLE-ERRORinvalid role
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_DELETE_ROLE

◆ omq.system.delete-service()

string omq.system.delete-service ( string  name,
*string  version 
)

Unloads the named system service from the system.

If the service is running, it is first stopped. Additionally, any outstanding method calls must return before the service can be unloaded.

Parameters
namethe name of the system service to unload
versionthe version of the service to unload; normally this parameter should not be given; only one version of a service can be loaded at a time and giving the wrong version string will cause an exception to be thrown
Returns
"OK"
Note
does not delete any data from the system database schema; only unloads the service from memory
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-NOT-LOADEDthis exception is thrown when the service is not loaded
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_UNLOAD_SERVICE

◆ omq.system.delete-user()

string omq.system.delete-user ( string  user)

Deletes an existing user from the database and the RBAC cache.

Parameters
userthe user to delete
Returns
"OK"
Exceptions
RBAC-DELETE-USER-ERRORinvalid user
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_DELETE_USER

◆ omq.system.delete-workflow-error()

bool omq.system.delete-workflow-error ( softint  wfid,
string  err 
)

deletes a workflow-specific error so that the global error definition will be used instead

Changes are committed internally and also to the database in this method (i.e. all changes are persistent)

Parameters
wfidthe workflow ID of the workflow-specific error to delete
errthe name of the error to delete
Returns
True if the error was deleted, False if it did not exist
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
Since
Qorus 2.8.0

◆ omq.system.exec-synchronous-existing()

hash omq.system.exec-synchronous-existing ( hash  params)

Executes a workflow in synchronous mode against an already-existing order in the database with status OMQ::StatReady.

Starts a workflow execution instance in synchronous mode against the already existing workflow order data instance identified in the hash argument (must correspond to the WORKFLOW_INSTANCE.WORKFLOW_INSTANCE_ID value for the data to be processed). Note that the workflow must have a OMQ::StatReady or OMQ::StatScheduled (WORKFLOW_INSTANCE.WORKFLOW_STATUS = "Y" or "S") status in the database in order to be processed in a synchronous workflow instance; it's not possible to process workflow data with other statuses synchronously. The call will normally return only after the workflow reaches a OMQ::StatComplete or OMQ::StatError state, unless the system or the workflow order data instance are manually stopped while the workflow order data instance is being processed, in which case other statuses can be returned.

Parameters
paramsa hash with the following keys:
  • workflow_instanceid: the workflow instance ID of the order to process; this key is required to be set
  • options: (hash) an optional hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the synchronous workflow execution instance is not started
Returns
a hash with the following keys:
  • workflow_instanceid: the workflow instance ID of the order
  • status: the status of the workflow
  • dynamicdata: the dynamic data of the workflow order instance
Exceptions
PARAMETER-ERRORworkflow_instanceid key missing from argument hash
SHUTDOWN-IN-PROGRESScannot start new workflows because the system is shutting down
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires at least one of the following permissions: OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_EXEC_SYNC_WORKFLOW
See also
omq.system.exec-synchronous-workflow()

◆ omq.system.exec-synchronous-workflow()

hash omq.system.exec-synchronous-workflow ( hash  params)

Executes a workflow in synchronous mode and returns the final status of the order after processing.

Starts a workflow execution instance with the designated name and version in synchronous mode against the order data given in the call. The call will normally return only after the workflow reaches a OMQ::StatComplete or OMQ::StatError state, unless the system or the workflow order data instance are manually stopped while the workflow order data instance is being processed, in which case other statuses can be returned.

Parameters
paramsa hash with the following keys:
  • name: (string) the name of the workflow (required)
  • version: (string) the version of the workflow; if the version key is not supplied, then the latest version of the workflow is used
  • orderdata: (hash) the static workflow order data (required)
  • dynamicdata: (hash) the initial dynamic data for the workflow (optional)
  • options: (hash) a hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the workflow execution instance is not started (optional)
  • priority: the order priority (default OMQ::DefaultOrderPriority), ignored while the order is processed synchronously; from 0 - 999; priority 0 is the highest; 999 is the lowest
  • orderkeys: order keys for the order
  • external_order_instanceid: the optional external order instanceid for the order
  • parent_workflow_instanceid: a loosely-coupled workflow that will be marked as the parent of this workflow
Returns
a hash with the following keys:
  • workflow_instanceid: the workflow instance ID for the order created
  • status: the status of the workflow
  • dynamicdata: the dynamic data of the workflow order instance
  • version: (string) the version of the workflow executed (useful if no version key supplied in the call)
Exceptions
PARAMETER-ERRORinvalid workflow, mode, options key in incorrect format (not a hash), or orderdata key missing from argument hash
SHUTDOWN-IN-PROGRESScannot start new workflows because the system is shutting down
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires at least one of the following permissions: OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EXEC_SYNC_WORKFLOW
See also
omq.system.exec-synchronous-existing()

◆ omq.system.flush-options()

string omq.system.flush-options ( *hash  params)

write the server's options to the option file on the server's filesystem

If any option hash if passed, then such options will be saved in the file but not applied to the running process. If any errors occur, an exception will be thrown.

Parameters
paramsoptions to set in the options file
Returns
"OK"
Exceptions
OPTION-ERRORan error occurred in creating or writing to the output file
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_OPTION_CONTROL

◆ omq.system.get-all-errors()

hash omq.system.get-all-errors ( )

returns all global and workflow-specific error definitions

Returns
a hash with the following keys: "global" and "workflow"; the "global" key is assigned a hash of global error definitions, where each key is the error name and the value of each key is a hash representing the error definition. The "workflow" key is assigned a hash of workflow IDs, each of which is then assigned a hash of error definitions, representing the workflow-specific error definitions. Each error hash has the following keys:
  • error: the name of the error repeated
  • description: the description of the error
  • severity: the severity of the error (see Error Severity Codes for possible values)
  • business_flag: indicates if the error is a business error or a technical error
  • status: the status the order should fall in when the error occurs
  • retry_delay_secs: indicates the retry delay in seconds for this error; if not set then the error gets the standard retry period
Note
If RBAC is enabled, then any workflows that the user does not have access to will be filtered from the list returned
Since
Qorus 2.8.0

◆ omq.system.get-all-permissions()

hash omq.system.get-all-permissions ( )

returns a hash of information about all permissions in the RBAC cache

Returns
a hash where each key is a permission name and the values are hashes with the following keys:
  • permission_type: either "SYSTEM" or "USER"
  • desc: the desciption for the permission
  • provider: the RBAC provider for the role information

◆ omq.system.get-all-roles()

hash omq.system.get-all-roles ( )

Returns a hash with information on all roles in the RBAC cache.

Returns
a hash where each key is a role name and each value is a hash with the following keys:
  • role: the role name
  • provider: the RBAC provider for the role
  • desc: the description of the role
  • permissions: a list of permissions attached to the role
  • groups: a list of groups attached to the role
  • has_default: True if the has group DEFAULT, in this case workflows, services, and jobs keys will be assigned to empty lists and the role has the right to access all workflows, services, and jobs
  • workflows: a list of hashes of workflow information that the role may access (empty if has_default is True); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the role may access (empty if has_default is True); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the role may access (empty if has_default is True); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job
Note
requires permission OMQ::QR_USER_CONTROL

◆ omq.system.get-all-users()

hash omq.system.get-all-users ( )

Returns a hash with all information (except passwords) on all Qorus users in the RBAC cache.

Returns
a hash where each key is a user name and each value is a user hash with the following keys:
  • username: the username of the user (same as the higher-level hash key)
  • name: the descriptive (or real) name for the user
  • provider: the RBAC provider for the user
  • permissions: a list of all permissions that the user has inherited through all roles
  • groups: a list of groups that the user has inherited through all roles
  • has_default: True if the user has any roles that have group DEFAULT, in this case the workflows, services, and jobs keys will be assigned to empty lists and the user has the right to access all workflows, services, and jobs
  • workflows: a list of hashes of workflow information that the user may access (empty if has_default is True); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the user may access (empty if has_default is True); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the user may access (empty if has_default is True); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL

◆ omq.system.get-current-user-info()

hash omq.system.get-current-user-info ( )

Returns a hash with all information (except passwords) on for the current user from the RBAC cache.

Returns
a user hash with the following keys:
  • username: the username of the user
  • name: the descriptive (or real) name for the user
  • provider: the RBAC provider for the user
  • roles: a list of roles assigned to the user
  • permissions: a list of all permissions that the user has inherited through all roles
  • groups: a list of groups that the user has inherited through all roles
  • has_default: True if the user has any roles that have group DEFAULT, in this case the workflows, services, and jobs keys will be assigned to empty lists and the user has the right to access all workflows, services, and jobs
  • workflows: a list of hashes of workflow information that the user may access (empty if has_default is True); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the user may access (empty if has_default is True); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the user may access (empty if has_default is True); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job
  • storage: a hash of key-value pairs associated with the user

◆ omq.system.get-global-errors()

* hash omq.system.get-global-errors ( *softlist  l)

returns global error definition information

Parameters
lNOTHING (meaning return all errors) or a single string (meaning return the global definition for that error string) or a list of strings (meaning return a hash of the requested errors)
Returns
nothing if no errors match the arguments or a hash of global error definitions, each key is the error name, and the values are hashes with the following keys:
  • error: the name of the error repeated
  • description: the description of the error
  • severity: the severity of the error (see Error Severity Codes for possible values)
  • business_flag: indicates if the error is a business error or a technical error
  • retry_flag: indicates if the error should cause the order to get a "RETRY" status
  • retry_delay_secs: indicates the retry delay in seconds for this error; if not set then the error gets the standard retry period
  • type: "global", meaning that the error definition is global
Since
Qorus 2.8.0

◆ omq.system.get-last-event-id()

int omq.system.get-last-event-id ( )

returns the last system event ID generated

Returns
the last system event ID generated

◆ omq.system.get-last-events()

hash omq.system.get-last-events ( softint  count)

returns the last system events

Parameters
countthe maximum number of events to return
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the function returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
See also
Since
Qorus 2.0.2
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.system.get-last-events-and()

hash omq.system.get-last-events-and ( softint  count,
*softlist  filter,
*softlist  or_not,
*softlist  nfilt 
)

gets the last system events that meet all of the filter criteria or none of the "or_not" criteria, if present

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument is the criteria list for “logical and” comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure “logical and” behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system's event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted “logical or” logic, the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
nfiltthis argument is an optional criteria list which will filter out elements matched by the above rules; if any event matched by the above rules then matches all the hash values in any of the elements of this list, then it's filtered out of the result list
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the function returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
See also
Since
Qorus 2.0.2, Qorus 3.0 added the nfilt argument
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.system.get-last-events-or()

hash omq.system.get-last-events-or ( softint  count,
*softlist  filter,
*softlist  and_not,
*softlist  nfilt 
)

gets the last system events that meet any of the filter criteria and none of the "and_not" criteria, if present

Returns a hash giving the list of the most recent system events matching a filter and the last event ID generated by the system. Events in the event list returned must match the criteria passed as the second argument; if any of the criteria match an event, then it is included in the return list, unless a third criteria list argument is also passed, which allows for removing elements from the list returned.

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument gives the criteria list for “logical or” comparisons to be applied to the events. If an event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional third argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure “logical or” behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure “logical and” filtering the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
nfiltthis argument is an optional criteria list which will filter out elements matched by the above rules; if any event matched by the above rules then matches all the hash values in any of the elements of this list, then it's filtered out of the result list
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the function returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
See also
Since
Qorus 2.0.2, Qorus 3.0 added the nfilt argument
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.system.get-listeners()

hash omq.system.get-listeners ( )

returns a hash of listener information for the HTTP server

Returns
a hash where the keys are the listener IDs and the values are hashes with the following keys:
  • proto: http or https
  • bind: the bind address of the listener
Since
Qorus 2.6.0

◆ omq.system.get-option-info()

hash omq.system.get-option-info ( )

returns a hash of all global Qorus system options and their current values

Returns
a hash of all global Qorus system options and their current values; hash keys:
  • value: (any) the value of the option
  • expects: (string) the data type the option expects
  • desc: (string) description of the option
  • default: (any) the default value of the option (if any)
  • startup-only: (boolean) if the option can only be set when the system is started
  • status: (string) either locked or unlocked

◆ omq.system.get-order-info()

hash omq.system.get-order-info ( softstring  wfiid)

Gets additional info for the given workflow order data instance.

Parameters
wfiidthe workflow instance id
Returns
a hash with the following keys:
  • op_username: the username of the operator working on the order
  • op_comment: notes about processing the order
Exceptions
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Since
Qorus 2.5.0
Deprecated:
This function is present for backwards-compatibility and uses Order Instance Notes

◆ omq.system.get-role-info()

hash omq.system.get-role-info ( string  role)

Returns a hash with information on all roles in the RBAC cache.

Returns
a hash with the following keys:
  • role: the role name
  • provider: the RBAC provider for the role
  • desc: the description of the role
  • permissions: a list of permissions attached to the role
  • groups: a list of groups attached to the role
  • has_default: True if the role has group DEFAULT, in this case workflows, services, and jobs keys will be assigned to empty lists and the role has the right to access all workflows, services, and jobs
  • workflows: a list of hashes of workflow information that the role may access (empty if has_default is True); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the role may access (empty if has_default is True); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the role may access (empty if has_default is True); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job
Exceptions
GET-ROLE-ERRORrole does not exist
Note
requires permission OMQ::QR_USER_CONTROL

◆ omq.system.get-service-autostart()

bool omq.system.get-service-autostart ( string  name)

returns the autostart status of the given system service

Parameters
namethe name of the system service
Returns
the autostart status

◆ omq.system.get-service-options()

any omq.system.get-service-options ( string  name)

Returns options set on the given system service; the service must be already loaded or an exception is raised.

If no arguments are passed, then all service-level options are returned, otherwise only the values for the given options are returned. If the given option is not overridden on the service level, then the value of the system option is returned. If the service is not already loaded is not valid, then an exception is raised.

Parameters
namethe service name
Returns
a single value if only a single option is requested, a hash of options if nore than one option is requested; note that the value for the option returned may by NOTHING if the given option is not set at the service level
Exceptions
SERVICE-ERRORthe given service is not loaded
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

◆ omq.system.get-status()

hash omq.system.get-status ( )

returns a hash giving information about system status

Returns
a hash giving information about system status; hash keys:
  • instance-key: (string) the system instance key
  • session-id: (int) the application session id
  • omq-version: (string) the version of the server
  • qore-version: (string) the version of the underlying qore library used
  • modules: (hash) a hash of module info as returned by Qore::get_module_hash()
  • datamodel-version: (string) the version of the datamodel expected by the server
  • omq-schema: (string) "user@dbname" string for the system "omq" datasource
  • omq-driver: (string) driver name for the system "omq" datasource
  • omq-db-version: (string) database server version for the system "omq" datasource
  • omquser-schema: (string) "user@dbname" string for the "omquser" datasource
  • omquser-driver: (string) driver name for the "omquser" datasource
  • omquser-db-version: (string) database server version for the "omquser" datasource
  • starttime: (date) date and time the server was started
  • hostname: (string) hostname where the server is running
  • pid: (int) PID of the server process
  • threads: (int) count of currently active threads
  • schema-properties: (hash) hash of actual schema properties (identical to system property domain "omq")
  • omq_dir: (string) the application directory or "LSB" for Linux Standard Base filesystem integration
  • logfile: (string) path to system log file
  • http_logfile: (string) path to system HTTP server log file
  • monitoring_logfile: (string) path to system monitoring log file
  • alert_logfile: (string) path to system alert log file
  • cache_size: (int) the current size of the workflow order data cache
  • shutting_down: (bool) a flag if the system is shutting down
  • build-type: (string) the type of build of the server ("Production" or "Debug")
  • runtime-properties: (hash) a hash of runtime properties
  • alert-summary: (hash) a hash with the following keys:
    • transient: (int) number of transient alerts
    • ongoing: (int) number of ongoing alerts
  • debug: system debugging flag (when True then more information is provided with exceptions)
  • health: a string color code for the health of the system with the following values:
    • "GREEN": good health
    • "YELLOW": warning
    • "RED": problems
  • system_log_url: a URL to the websocket source for the main system log
  • audit_log_url: a URL to the websocket source for the audit log
  • http_log_url: a URL to the websocket source for the HTTP server log
  • mon_log_url: a URL to the websocket source for the monitoring log
  • alert_log_url: a URL to the websocket source for the alert log

◆ omq.system.get-user-info()

hash omq.system.get-user-info ( *string  user)

Returns a hash with all information (except passwords) on for the given or current user from the RBAC cache.

Parameters
userif present, the username to query, if not present, returns information about the current user
Returns
a user hash with the following keys:
  • username: the username of the user
  • name: the descriptive (or real) name for the user
  • provider: the RBAC provider for the user
  • roles: a list of roles assigned to the user
  • permissions: a list of all permissions that the user has inherited through all roles
  • groups: a list of groups that the user has inherited through all roles
  • has_default: True if the user has any roles that have group DEFAULT, in this case workflows, services, and jobs keys will be assigned to empty lists and the user has the right to access all workflows, services, and jobs
  • workflows: a list of hashes of workflow information that the user may access (empty if has_default is True); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the user may access (empty if has_default is True); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the user may access (empty if has_default is True); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job
  • storage: a hash of key-value pairs associated with the user
Exceptions
GET-USER-ERRORno username supplied in call and no authentication information supplied, username does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_USER to retrieve information about other users

◆ omq.system.get-workflow-errors()

* hash omq.system.get-workflow-errors ( softint  wfid,
*softlist  l 
)

returns workflow-specific error definition information

Parameters
wfidthe workflowid of the workflow to query
lnothing (meaning return all workflow-specific errors for this workflow) or a single string (meaning return the definition for that error string that will be used for the given workflow) or a list of strings (meaning return a hash of the requested errors used for the given workflow)
Returns
nothing if no errors match the arguments or a hash of error definitions, each key is the error name, and the values are hashes with the following keys:
  • error: the name of the error repeated
  • description: the description of the error
  • severity: the severity of the error (see Error Severity Codes for possible values)
  • business_flag: indicates if the error is a business error or a technical error
  • retry_flag: indicates if the error should cause the order to get a "RETRY" status
  • retry_delay_secs: indicates the retry delay in seconds for this error; if not set then the error gets the standard retry period
  • type: either "workflow", meaning that the error definition is workflow-specific, or "global", meaning that the error definition is global
Exceptions
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Since
Qorus 2.8.0

◆ omq.system.get-workflow-info()

any omq.system.get-workflow-info ( *softstring  id)

returns workflow information for the execution id passed, or for all workflows if no execution id is passed

Parameters
idthe optional workflow execution id
Returns
if id is passed, then a single hash is returned, otherwise a list of workflow information hashes is returned. The workflow information hash has the following format:
  • executionID: (string) the execution ID of the workflow
  • name: (string) the name of the workflow
  • version: (string) the version of the workflow
  • workflowid: (string) the ID of the workflow
  • mode: (string) the mode of the workflow
  • status: (string) the status of the workflow
  • iterations: (int) number of iterations of all segments
  • totalSegments: (int) number of segments in the workflow
  • errors: (int) number of errors encountered
  • warnings: (int) number of warnings encountered
  • starttime: (date) date and time workflow execution instance started
  • options: (hash) workflow options
  • logfile: (string) the workflow log file
Exceptions
INVALID-WORKFLOW-EXECUTION-IDinvlaid workflow execution ID
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

◆ omq.system.get-workflow-option()

any omq.system.get-workflow-option ( softint  id)

Returns options set on the running workflow identified by the execution ID passed.

Additional optional string arguments giving option names are accepted after the execution ID. If no additional arguments are passed, then all options set on the workflow are returned, otherwise only the values for the given options are returned.

When returning individual option values, any option that is not set at the workflow level will be returned with the value system level if the option is a valid system option.

If the execution instance ID is not valid, then an exception is raised

Parameters
idthe workflow execution ID
Returns
a hash of options set for the workflow or NOTHING if no options are set
Exceptions
INVALID-WORKFLOW-EXECUTION-IDinvalid workflow execution ID
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • workflow options are now actually global for the given workflow; this API takes an execution instance ID, but the options are still set against the workflow and not just on the execution instance level (global workflow options were implemented in Qorus 3.0.0)
  • workflow options are persistent (persistent workflow options were implemented in Qorus 3.0.0)
Since
Qorus 3.0.0 workflow options are global and persistent

◆ omq.system.get-workflow-options()

hash omq.system.get-workflow-options ( softint  id)

Returns all options set on the running workflow identified by the execution ID passed.

If the execution instance ID is not valid, then an exception is raised

Parameters
idthe workflow execution ID
Returns
a hash of options set for the workflow or NOTHING if no options are set
Exceptions
INVALID-WORKFLOW-EXECUTION-IDinvalid workflow execution ID
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • workflow options are now actually global for the given workflow; this API takes an execution instance ID, but the options are still set against the workflow and not just on the execution instance level (global workflow options were implemented in Qorus 3.0.0)
  • workflow options are persistent (persistent workflow options were implemented in Qorus 3.0.0)
Since
Qorus 3.0.0 workflow options are global and persistent

◆ omq.system.group.add-job()

nothing omq.system.group.add-job ( string  name,
string  jname 
)

Adds a job to a workflow/service/job group from the job's name.

If a job is added to a disabled group and the job is active, then the job is immediately stopped

Parameters
namethe name of the group
jnamethe name of the job to add
Exceptions
GROUP-ERRORgroup or job does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.1
See also
omq.system.group.update()

◆ omq.system.group.add-job-id()

nothing omq.system.group.add-job-id ( string  name,
softlist  ids 
)

Adds one or more jobs to a workflow/service/job group from the jobids.

If jobs are added to a disabled group, the jobs are immediately stopped

Parameters
namethe name of the group
idsa list of job ids or a single job id
Exceptions
GROUP-ERRORgroup or job does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.1
See also
omq.system.group.update()

◆ omq.system.group.add-service()

nothing omq.system.group.add-service ( string  name,
string  sname,
*string  ver 
)

Adds a service to a workflow/service/job group from the service's name and optional version.

If a service is added to a disabled group, the any instances of the service are immediately stopped

Parameters
namethe name of the group
snamethe name of the service to add
verthe optional version of the service to add; if no version string is passed, then all existing versions of the service are added
Exceptions
GROUP-ERRORgroup or service does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.add-service-id()

nothing omq.system.group.add-service-id ( string  name,
softlist  ids 
)

Adds one or more services to a workflow/service/job group from the serviceids.

If services are added to a disabled group, the services are immediately stopped and unloaded

Parameters
namethe name of the group
idsa list of service ids or a single service id
Exceptions
GROUP-ERRORgroup or service does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.add-workflow()

nothing omq.system.group.add-workflow ( string  name,
string  wname,
*string  ver 
)

Adds a workflow to a workflow/service/job group from the workflow's name and optional version.

If a workflow is added to a disabled group, the any instances of the workflow are immediately stopped

Parameters
namethe name of the group
wnamethe name of the workflow to add
verthe optional version of the workflow to add; if no version string is passed, then all existing versions of the workflow are added
Exceptions
GROUP-ERRORgroup or workflow does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.add-workflow-id()

nothing omq.system.group.add-workflow-id ( string  name,
softlist  ids 
)

Adds one or more workflows to a workflow/service/job group from the workflowids.

If a workflow is added to a disabled group, the any instances of the workflow are immediately stopped

Parameters
namethe name of the group
idsa list of workflow ids or a single workflow id
Exceptions
GROUP-ERRORgroup or workflow does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.create()

int omq.system.group.create ( string  name,
string  desc,
softlist  svcids,
softlist  wfids,
softstring  enabled = True,
softlist  jobids = (),
softlist  mapperids = (),
softlist  vmapids = () 
)

Creates an interface group.

Workflows, services, and jobs in disabled groups are stopped immediately if loaded/running. When a group is enabled, then any services with the autostart flag set and any jobs with the active flag set are immediately started if the group was previously disabled and the service/job is not a member of any other disabled group.

Parameters
namethe name of the group
descthe description of the group
svcidsa list of integer service IDs
wfidsa list of integer workflow IDs
enabledthe new status of the group (to be parsed with parse_boolean())
jobidsa list of integer job IDs
mapperidsa list of integer mapper IDs
vmapidsa list of integer value map IDs
Returns
the group ID of the new group
Exceptions
GROUP-ERRORgroup already exists, invalid service, workflow, or job ID
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_ADD_GROUP
Since
Qorus 2.6.0

◆ omq.system.group.delete()

nothing omq.system.group.delete ( string  name)

Permanently deletes a workflow/service/job group.

When a disabled group is deleted, then any services with the autostart flag set and any active jobs are immediately started if the group was previously disabled and the service/job is not a member of any other disabled group

Parameters
namethe name of the group
Exceptions
GROUP-ERRORgroup does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_DELETE_GROUP
Since
Qorus 2.6.0

◆ omq.system.group.delete-job()

nothing omq.system.group.delete-job ( string  name,
string  jname 
)

Permanently deletes a job from an interface group using the job's name.

No error is raised if an attempt is made to remove jobs from a group that are not in the group

Parameters
namethe name of the group
jnamethe name of the job to delete
Exceptions
GROUP-ERRORgroup or job does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.1.p2
See also
omq.system.group.update()

◆ omq.system.group.delete-job-id()

nothing omq.system.group.delete-job-id ( string  name,
softlist  ids 
)

Permanently deletes one or more jobs from an interface group using job ids.

Parameters
namethe name of the group
idsa list of job ids or a single job id
Exceptions
GROUP-ERRORgroup or job does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.1.p2
See also
omq.system.group.update()

◆ omq.system.group.delete-service()

nothing omq.system.group.delete-service ( string  name,
string  sname,
*string  ver 
)

Permanently deletes a service from a workflow/service/job group using the service's name and optional version.

No error is raised if an attempt is made to remove service from a group that are not in the group. When services are removed from disabled groups, any services with the autostart flag are immediately started if the group was previously disabled and the service is not a member of any other disabled group.

Parameters
namethe name of the group
snamethe name of the service to delete
verthe optional version of the service to delete; if no version string is passed, then all existing versions of the service are deleted
Exceptions
GROUP-ERRORgroup or service does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.delete-service-id()

nothing omq.system.group.delete-service-id ( string  name,
softlist  ids 
)

Permanently deletes one or more services to a workflow/service/job group from the service ids.

When services are removed from disabled groups, any services with the autostart flag are immediately started if the group was previously disabled and the service is not a member of any other disabled group.

Parameters
namethe name of the group
idsa list of service ids or a single service id
Exceptions
GROUP-ERRORgroup or service does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.delete-workflow()

nothing omq.system.group.delete-workflow ( string  name,
string  wname,
*string  ver 
)

Permanently deletes a workflow from a workflow/service/job group using the workflow's name and optional version.

No error is raised if an attempt is made to remove workflows from a group that are not in the group

Parameters
namethe name of the group
wnamethe name of the workflow to delete
verthe optional version of the workflow to delete; if no version string is passed, then all existing versions of the workflow are deleted
Exceptions
GROUP-ERRORgroup or workflow does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.delete-workflow-id()

nothing omq.system.group.delete-workflow-id ( string  name,
softlist  ids 
)

Permanently deletes one or more workflows from a workflow/service/job group using workflow ids.

Parameters
namethe name of the group
idsa list of workflow ids or a single workflow id
Exceptions
GROUP-ERRORgroup or workflow does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.0
See also
omq.system.group.update()

◆ omq.system.group.info()

hash omq.system.group.info ( *string  name)

Returns information for a group or all groups if no group name argument is passed.

Parameters
namethe optional name of the group to query; if no group name is passed, then information for all groups is returned
Returns
if no argument is passed, then the hash is keyed by group names with each value a group information hash, otherwise a group information hash is directly returned with the following keys:
  • name: the name of the group
  • description: the description of the group
  • enabled: True if enabled or False if disabled
  • is_default: True if the group is the DEFAULT group, in this case the workflows, services, and jobs keys will be assigned to empty lists and the group authorizes access all workflows, services, and jobs
  • id: the id of the group
  • roles: a list of roles that have the group
  • workflows: a list of hashes of workflow information that the group authorizes access to (empty if is_default is True, otherwise if is_default is False and this list is empty, it means that the group does not authorize access to any workflows); each hash has the following keys:
    • workflowid: the ID of the workflow
    • name: the name of the workflow
    • version: the version of the workflow
  • services: a list of hashes of user service information the group authorizes access to (empty if is_default is True, otherwise if is_default is False and this list is empty, it means that the group does not authorize access to any services); each hash has the following keys:
    • serviceid: the ID of the service
    • type: always "user"; it's not possible to restrict access to system services through interface groups
    • name: the name of the service
    • version: the version of the service
    • autostart: the autostart flag for the service
  • jobs: a list of hashes of job information the group authorizes access to (empty if is_default is True, otherwise if is_default is False and this list is empty, it means that the group does not authorize access to any jobs); each hash has the following keys:
    • jobid: the ID of the job
    • name: the name of the job
    • version: the version of the job

◆ omq.system.group.set-status()

nothing omq.system.group.set-status ( string  name,
softstring  enabled 
)

Enables or disables an interface group.

Workflows, services, and jobs in disabled groups are stopped immediately if loaded/running/active. When a group is enabled, then any services with the autostart flag are immediately started if the group was previously disabled and the service is not a member of any other disabled group.

Parameters
namethe name of the group
enabledthe new status of the group
Exceptions
GROUP-ERRORgroup does not exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
Since
Qorus 2.6.0

◆ omq.system.group.update()

string omq.system.group.update ( string  group,
hash  hash 
)

Modifies an existing interface group in the database and in the RBAC cache.

Changes to groups are effected immediately; for example, if a workflow, service, or job is added to a disabled group, the any corresponding running objects are immediately stopped; or if a job is removed from a disabled group, then it is immediately started, etc

Parameters
groupthe group to update
hasha hash giving the information to update, valid keys are as follows; at least one of the following keys must be present:
  • desc: (string) the new description of the group
  • workflows: (list of strings or a single string) the list of workflow names to include in the group; the new list will replace the current list unless the workflow names are preceded by "+" or "-", meaning add or remove a workflow, respectively (in which case all workflow names must be preceded by a "+" or "-"); note that if the key is present and contains an empty list or string then all workflows are removed from the group
  • services: (list of strings or a single string) the list of user service names to include in the group; the new list will replace the current list unless the user service names are preceded by "+" or "-", meaning add or remove a service, respectively (in which case all service names must be preceded by a "+" or "-"); note that if the key is present and contains an empty list or string then all services are removed from the group
  • jobs: (list of strings or a single string) the list of job names to include in the group; the new list will replace the current list unless the job names are preceded by "+" or "-", meaning add or remove a job, respectively (in which case all job names must be preceded by a "+" or "-"); note that if the key is present and contains an empty list or string then all jobs are removed from the group
  • mappers: (list of strings or a single string) the list of mapper names to include in the group; the new list will replace the current list unless the mapper names are preceded by "+" or "-", meaning add or remove a mapper, respectively (in which case all mapper names must be preceded by a "+" or "-"); note that if the key is present and contains an empty list or string then all mappers are removed from the group
  • vmaps: (list of strings or a single string) the list of value map names to include in the group; the new list will replace the current list unless the value map names are preceded by "+" or "-", meaning add or remove a value map, respectively (in which case all value map names must be preceded by a "+" or "-"); note that if the key is present and contains an empty list or string then all value maps are removed from the group
  • enabled: (string) this value will be processed by parse_boolean(); enables or disables the group
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_MODIFY_GROUP
Since
Qorus 2.6.3.p2

◆ omq.system.help()

hash omq.system.help ( )

gives a hash of API information, where each key is a Qorus system API method

This method accepts optional string arguments will select the methods to provide help for; if the method name has no '.' in it, then "omq.system." will be prepended. For example:

omq.system.help("add-user");

This will produce the following response:

omq.system.add-user:
params: "username, password, descriptive_name, permission_list, groups"
category: "permission based access control"
maskargs: 1
description: "creates a new RBAC user"
Returns
a hash of API information, where each key is a Qorus system API method, if arguments are supplied, then only methods given by the arguments are returned in the response hash. The hash keys are the command names, and the values are hashes with at least the following keys:
  • params: a description of the parameters
  • category: a string giving the method category
  • description: a description of the method

◆ omq.system.job.get-options()

any omq.system.job.get-options ( string  name)

Returns options set on the given job; the job must be active or an exception is raised.

If no arguments are passed, then all service-level options are returned, otherwise only the values for the given options are returned. If the given option is not overridden on the job level, then the value of the system option is returned. If the job is not active, then an exception is raised.

Parameters
namethe job name
Returns
a single value if only a single option is requested, a hash of options if nore than one option is requested; note that the value for the option returned may by NOTHING if the given option is not set at the job level
Exceptions
JOB-ERRORno job with the given name is active
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Since
Qorus 2.8.0

◆ omq.system.job.get-options-id()

any omq.system.job.get-options-id ( softint  id)

Returns options set on the given job; the job must be active or an exception is raised.

If no arguments are passed, then all service-level options are returned, otherwise only the values for the given options are returned. If the given option is not overridden on the job level, then the value of the system option is returned. If the job is not active, then an exception is raised.

Parameters
idthe job ID
Returns
a single value if only a single option is requested, a hash of options if nore than one option is requested; note that the value for the option returned may by NOTHING if the given option is not set at the job level
Exceptions
JOB-ERRORno job with the given name is active
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Since
Qorus 2.8.0

◆ omq.system.job.info()

hash omq.system.job.info ( *string  name)

Returns information on all jobs visible to the calling user or a specific job depending on the argument (or lack thereof)

Parameters
namethe optional name of the job to query; if no job name is passed, then information for all jobs is returned (note that the hash is filtered for jobs not visible to the calling user if the calling user has no role with the DEFAULT interface group), however, if this argument is passed and no job with this name exists, then a JOB-ERROR exception is raised
Returns
if no argument is passed, then the hash is keyed by job names with each value a job information hash, otherwise a job information hash is directly returned with the following keys:
  • jobid: the metadata jobid of the job type
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • [job_instanceid]: the id of the job instance (will only have a value if the job is currently executing)
  • [last_executed]: the last executed date/time of the job (NOTHING if not yet executed)
  • [last_executed_job_instanceid]: the last executed instance id of the job
  • [expiry_date]: the expiry date of the job, if any; if this date is present, then the job will not run automatically after this date
  • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
  • [next]: the next trigger date/time; this key is only included if the job is active
  • active: this value will only be True if the job is actually loaded; note that the job can be active in the database but not actually loaded if the job is a member of a disabled Interface Group, in which case the value of this key will be False
  • groups: a list of zero or more strings giving group names the job is a member of
Exceptions
JOB-ERRORno job with the given name exists
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Since
Qorus 2.6.1

◆ omq.system.job.info-id()

hash omq.system.job.info-id ( softint  id)

Returns information on a specific job by the jobid.

Parameters
idthe jobid of the job to query
Returns
a job information hash is returned with the following keys:
  • jobid: the metadata jobid of the job type
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • [job_instanceid]: the id of the job instance (will only have a value if the job is currently executing)
  • [last_executed]: the last executed date/time of the job (NOTHING if not yet executed)
  • [last_executed_job_instanceid]: the last executed instance id of the job
  • [expiry_date]: the expiry date of the job, if any; if this date is present, then the job will not run automatically after this date
  • single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
  • [next]: the next trigger date/time
  • active: this value will only be True if the job is actually loaded; note that the job can be active in the database but not actually loaded if the job is a member of a disabled Interface Group, in which case the value of this key will be False
Exceptions
JOB-ERRORno job with the given id exists
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Since
Qorus 2.6.1

◆ omq.system.job.list-active()

hash omq.system.job.list-active ( )

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

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

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

◆ omq.system.job.reset()

string omq.system.job.reset ( string  name)

Reloads a job from the database from its name; if it's currently running it is stopped and reloaded.

This API works on all jobs regardless of state; the job does not have to be running or active to be reset.

Parameters
namethe name of the job to reset
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given name exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
API-CALL-ERRORcannot reset a disabled job
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESET_JOB
Since
Qorus 2.6.1

◆ omq.system.job.reset-all()

string omq.system.job.reset-all ( )

Reloads all jobs from the database; all currently-running jobs are stopped and reloaded.

Returns
a string giving a description of the result of the operation
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESET_JOB
Since
Qorus 2.6.1

◆ omq.system.job.reset-id()

string omq.system.job.reset-id ( softint  id)

Reloads a job from the database from its id; if it's currently running it is stopped and reloaded.

This API works on all jobs regardless of state; the job does not have to be running or active to be reset.

Parameters
idthe jobid to reset
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given name exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESET_JOB
Since
Qorus 2.6.1

◆ omq.system.job.run()

hash omq.system.job.run ( string  name)

Runs the given job immediately (regardless of the trigger time) from the job name even if the job is expired, inactive, or dedicated to another instance.

Parameters
namethe name of the job to run
Returns
a hash with the following keys:
  • job_instanceid: the job_instanceid
  • status: the status of the execution of the job
Exceptions
JOB-ERRORno job with the given name exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RUN_JOB
Since
Qorus 2.6.1

◆ omq.system.job.run-id()

hash omq.system.job.run-id ( softint  id)

Runs the given job immediately (regardless of the trigger time) from the jobid even if the job is expired, inactive, or dedicated to another instance.

Parameters
idthe jobid to run
Returns
a hash with the following keys:
  • job_instanceid: the job_instanceid
  • status: the status of the execution of the job
Exceptions
JOB-ERRORno job with the given jobid exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RUN_JOB
Since
Qorus 2.6.1

◆ omq.system.job.schedule()

string omq.system.job.schedule ( string  name,
*string  schedule,
*softint  recurring 
)

Updates a job's schedule from the job name; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated.

Parameters
namethe name of the job to update
schedulea cron-like string giving the job schedule, see Job Cron Schedule for information about the format; either this parameter or recurring must be present, but not both
recurringa duration in sections for triggering the job; either this parameter or schedule must be present, but not both
Returns
a string giving a description of the result of the operation
Exceptions
JOB-SCHEDULE-ERRORboth schedule and duration parameters given or neither given
CRON-ERRORcron schedule cannot be parsed or 0 second duration given
JOB-ERRORno job with the given name exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESCHEDULE_JOB
Since
Qorus 2.6.1.p4

◆ omq.system.job.schedule-id()

string omq.system.job.schedule-id ( softint  id,
*string  schedule,
*softint  recurring 
)

Updates a job's schedule from the jobid; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated.

Parameters
idthe jobid to update
schedulea cron-like string giving the job schedule, see Job Cron Schedule for information about the format; either this parameter or recurring must be present, but not both
recurringa duration in sections for triggering the job; either this parameter or recurring must be present, but not both
Returns
a string giving a description of the result of the operation
Exceptions
JOB-SCHEDULE-ERRORboth schedule and duration parameters given or neither given
CRON-ERRORcron schedule cannot be parsed or 0 second duration given
JOB-ERRORno job with the given ID exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESCHEDULE_JOB
Since
Qorus 2.6.1.p4

◆ omq.system.job.set-active()

string omq.system.job.set-active ( string  name,
*softstring  active 
)

Updates the "active" status of a job from the job name; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated. Updating a job to active will start the job immediately unless the expiry date is past or the job is a member of a disabled group. Changing a currently-active job to inactive will stop the job immediately.

Parameters
namethe name of the job to update
activethe new status of the job; if not present, then True is assumed; note that this parameter is parsed with parse_boolean() so it's safe to pass a boolean, or a string like "true" or an integer that will be converted to a boolean value, see parse_boolean() for more information
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given name exist
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_MODIFY_JOB_STATUS
Since
Qorus 2.6.1

◆ omq.system.job.set-active-id()

string omq.system.job.set-active-id ( softint  id,
*softstring  active 
)

Updates the "active" status of a job from the job id; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated. Updating a job to active will start the job immediately unless the expiry date is past or the job is a member of a disabled group. Changing a currently-active job to inactive will stop the job immediately.

Parameters
idthe jobid of the job to update
activethe new status of the job; if not present, then True is assumed; note that this parameter is parsed with parse_boolean() so it's safe to pass a boolean, or a string like "true" or an integer that will be converted to a boolean value, see parse_boolean() for more information
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given id exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_MODIFY_JOB_STATUS
Since
Qorus 2.6.1

◆ omq.system.job.set-expiry()

string omq.system.job.set-expiry ( string  name,
*date  expiry 
)

Updates the expiry date of a job from the job name; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated. Removing the expiry date or setting a future expiry date from a job that is not started because it has expired will result in the job starting immediately (unless the job is inactive or a member of a disabled group. Setting a past expiry date on a currently-active job will stop the job immediately.

Parameters
namethe name of the job to update
expirythe new expiration date for the job; if this parameter is not present or NOTHING then any expiration date for the job will be removed
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given name exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_MODIFY_JOB_EXPIRY
Since
Qorus 2.6.1

◆ omq.system.job.set-expiry-id()

string omq.system.job.set-expiry-id ( softint  id,
*date  expiry 
)

Updates the expiry date of a job from the job id; if any errors occur an exception is thrown.

This API works on all jobs regardless of state; the job does not have to be running or active to be updated. Removing the expiry date or setting a future expiry date from a job that is not started because it has expired will result in the job starting immediately (unless the job is inactive or a member of a disabled group. Setting a past expiry date on a currently-active job will stop the job immediately.

Parameters
idthe jobid to update
expirythe new expiration date for the job; if this parameter is not present or NOTHING then any expiration date for the job will be removed
Returns
a string giving a description of the result of the operation
Exceptions
JOB-ERRORno job with the given id exists
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_MODIFY_JOB_EXPIRY
Since
Qorus 2.6.1

◆ omq.system.job.set-options()

string omq.system.job.set-options ( string  name,
hash  hash 
)

Sets the options given in the hash on the given job; the job must be active or an exception is raised.

Options set override the system options of the same name; only system options valid for jobs may be set. If an exception is thrown due to an option error, all other options will still be set.

Parameters
namethe name of the job to set options on
hashoption-value pairs
Returns
"OK"
Exceptions
JOB-ERRORno job with the given name is active
JOB-OPTION-ERRORinvalid option
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_SET_JOB_OPTIONS
Since
Qorus 2.8.0

◆ omq.system.job.set-options-id()

string omq.system.job.set-options-id ( softint  id,
hash  hash 
)

Sets the options given in the hash on the given job; the job must be active or an exception is raised.

Options set override the system options of the same name; only system options valid for jobs may be set. If an exception is thrown due to an option error, all other options will still be set.

Parameters
idthe ID of the job to set options on
hashoption-value pairs
Returns
"OK"
Exceptions
JOB-ERRORno job with the given name is active
JOB-OPTION-ERRORinvalid option
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
JOB-ACCESS-ERRORthe user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_SET_JOB_OPTIONS
Since
Qorus 2.8.0

◆ omq.system.list-all-services()

any omq.system.list-all-services ( *date  date)

returns a list of all services currently loaded or a constant string if the services have not been updated since the optional date argument

Parameters
datean optional date argument; if given and the service cache has not been updated since the date, a constant string is returned instead of a list of services
Returns
a list of all services currently loaded or a constant string if the services have not been updated since the optional date argument; if a list is returned, each element is a hash with the following keys:
  • type: "user" or "system"
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • log: log file path
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys for each method
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
    • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
    • desc: a hashdecl description of the resource
    • info: a hash with additional, free-form information about the resource
  • groups: a list of zero or more strings giving interface group names the service is a member of
Note
if RBAC is enabled and the user does not have access to all user services, only the user services the user has access to will be reported in the list returned (however all system services will always be reported because system services are not subject to RBAC service access lists).
Since
2.6.3.p17 added the "log" key to the return hash

◆ omq.system.list-services()

list omq.system.list-services ( )

returns a list of all system services currently loaded

Returns
a list of all currently loaded system services; each element is a hash with the following keys:
  • type: "system"
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • log: log file path
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
    • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
    • desc: a hashdecl description of the resource
    • info: a hash with additional, free-form information about the resource
Since
2.6.3.p17 added the "log" key to the return hash

◆ omq.system.order-notes()

list omq.system.order-notes ( softstring  wfiid,
*softint  count 
)

Gets Order Instance Notes.

Parameters
wfiidthe workflow instance id
countan optional limit-count of returned notes
Returns
a hash with the notes. See Order Instance Notes
Exceptions
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Since
Qorus 3.0.2

◆ omq.system.passwd()

string omq.system.passwd ( softstring  oldpwd,
softstring  newpwd 
)

Changes the password for the current user.

Parameters
oldpwdthe current user password
newpwdthe new user password
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORno user info or invalid current password
Since
Qorus 2.8.0

◆ omq.system.ping()

string omq.system.ping ( )

Returns a constant "OK" string.

Useful for checking that the system is up and running

Returns
"OK"

◆ omq.system.post-event()

nothing omq.system.post-event ( softstring  eventtype,
softstring  eventkey 
)

Posts a workflow synchronization event with the event type name and key value.

Note that this API is not checked against the Interface Groups membership of the caller, because a synchronization event could be accessed by multiple workflows.

Parameters
eventtypethe event type name
eventkeythe event key in the event type queue to post
Exceptions
UNKNOWN-EVENTunknown event type name
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_POST_WORKFLOW_EVENT
See also
Since
Qorus 2.6.0

◆ omq.system.reload-errors()

hash omq.system.reload-errors ( )

reloads all error definitions from the DB

Returns
a hash with the following keys:
  • global: gives the number of global error definitions loaded
  • workflow: gives the number of all workflow-specific error definitions loaded
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
Since
Qorus 2.8.0

◆ omq.system.reload-rbac()

string omq.system.reload-rbac ( )

Reloads the all RBAC information (users, permissions, roles, groups) from the system schema.

Useful for updating Qorus after updating RBAC information with the offline user-tool program

Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_RELOAD_RBAC

◆ omq.system.replace-dynamic-data()

string omq.system.replace-dynamic-data ( softstring  wfiid,
*hash  data 
)

Replaces the dynamic data for the given workflow order data instance.

This API call should be used with care as erroneous changes to workflow order data instances can render further workflow processing impossible. If the workflow order data instance ID is not valid then an exception is thrown.

Parameters
wfiidthe workflow order data instance id
datathe dynamic data to replace
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

◆ omq.system.replace-static-data()

string omq.system.replace-static-data ( softstring  wfiid,
*hash  data 
)

Replaces the static data for the given workflow order data instance.

This API call should be used with care as erroneous changes to workflow order data instances can render further workflow processing impossible. If the workflow order data instance ID is not valid then an exception is thrown

Parameters
wfiidthe workflow order data instance id
datathe static data to replace
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

◆ omq.system.reprioritize-order()

string omq.system.reprioritize-order ( softint  wfiid,
softint  priority 
)

changes the priority for an existing workflow order data instance

The workflow order data must not have status OMQ::StatComplete

Parameters
wfiidthe workflow order instance ID
prioritythe new order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
Returns
"OK"
Exceptions
INVALID-WORKFLOW-INSTANCEinvalid workflow instance ID
SESSION-ERRORcannot reschedule workflow data owned by a foreign session
WORKFLOW-STATUS-ERRORworkflows with status OMQ::StatComplete cannot have their priority changed
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
Since
Qorus 2.6.0
See also
omq.system.reprioritize-orders()

◆ omq.system.reprioritize-orders()

hash omq.system.reprioritize-orders ( hash  ih)

changes the priority for a list of workflow order data instances

The workflow order data must not have status OMQ::StatComplete

Parameters
iha hash where the keys are workflow_instanceids to process and the value is an integer giving the new order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
Returns
a hash where the top-level keys are workflow_instanceids and the value is either an exception string (indicating that the operation failed for that order) or a constant string "OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_REPRIORITIZE_WORKFLOW_ORDER
Since
Qorus 2.6.0
See also
omq.system.reprioritize-order()

◆ omq.system.reschedule-order()

string omq.system.reschedule-order ( softint  wfiid,
*softdate  scheduled 
)

sets or removes the scheduled date for a workflow order data instance

Sets or removes the scheduled date for a workflow order data instance, which means that the workflow order data will not be processed before the scheduled date and time.

The workflow order data must normally have status OMQ::StatReady or OMQ::StatScheduled to be rescheduled, however also workflows with OMQ::StatCanceled and OMQ::StatBlocked statuses can be rescheduled if their original status is OMQ::StatReady or OMQ::StatScheduled.

Parameters
wfiidthe workflow order instance ID
scheduledthe scheduled date or NOTHING to clear the scheduled date
Returns
"OK"
Exceptions
INVALID-WORKFLOW-INSTANCEinvalid workflow instance ID
SESSION-ERRORcannot reschedule workflow data owned by a foreign session
WORKFLOW-STATUS-ERRORonly workflows with status OMQ::StatReady or OMQ::StatScheduled or blocked or canceled workflows with original status OMQ::StatReady or OMQ::StatScheduled can be rescheduled
RESCHEDULE-ERRORreschedule failed because workflow order data started processing while the request was being processed
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
Since
Qorus 2.6.0
See also
omq.system.reschedule-orders()

◆ omq.system.reschedule-orders()

hash omq.system.reschedule-orders ( hash  ih)

sets or removes the scheduled date for a list of workflow order data instances

Sets or removes the scheduled date for a list of workflow order data instance, which means that the workflow order data will not be processed before the scheduled date and time if the scheduled date is set. If the scheduled date is cleared, it means that the order can be processed at any time.

The workflow order data must normally have status OMQ::StatReady or OMQ::StatScheduled to be rescheduled, however also workflows with OMQ::StatCanceled and OMQ::StatBlocked statuses can be rescheduled if their original status is OMQ::StatReady or OMQ::StatScheduled.

Parameters
iha hash where the keys are workflow_instanceids to process and the value is either a scheduled date or NOTHING, indicating that the scheduled date should be cleared from the order
Returns
a hash where the top-level keys are workflow_instanceids and the value is either an exception string (indicating that the operation failed for that order) or a constant string "OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RESCHEDULE_WORKFLOW_ORDER
Since
Qorus 2.6.0
See also
omq.system.reschedule-order()

◆ omq.system.reset-all-services()

list omq.system.reset-all-services ( )

unloads all services currently loaded in memory and reloads them from the database

If the calling user has restricted access to user services, only services visible by the current user are reset.

Returns
list of hashes of services reset with the following keys:
  • type: either "system" or "user"
  • name: name of the service
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also
Since
Qorus 2.6.0

◆ omq.system.reset-all-workflows()

string omq.system.reset-all-workflows ( )

Deletes the configuration for all workflows from the workflow configuration cache.

If there are any running workflow execution instances then the reset will cause the workflow to be reloaded from the database on their next iteration.

If RBAC is enabled and the calling user does not have access to all workflows, then only the workflows that the user has access to will have their configurations removed from the workflow cache.

Returns
a string confirming the workflow(s) deleted from the cache
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_EXEC_CONTROL, or OMQ::QR_RESET_WORKFLOW

◆ omq.system.reset-service()

bool omq.system.reset-service ( string  name,
bool  load = False 
)

unloads a single system service and reloads it from the database

Parameters
namethe name of the system service to reset
loadif True then the service will be loaded and initialized if it was not already loaded
Returns
True if the service was already loaded before this call, False if not
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also
Since
Qorus 2.6.0

◆ omq.system.reset-services()

list omq.system.reset-services ( )

unloads all system services currently loaded in memory and reloads them from the database

Returns
list of hashes of services reset with the following keys:
  • type: always "system" with this call
  • name: name of the service
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also
Since
Qorus 2.6.0

◆ omq.system.reset-workflow()

string omq.system.reset-workflow ( string  name,
*string  version 
)

Deletes the configuration for the specified workflow from the cache.

If there are any running instances of the affected workflow(s) then the reset will cause the workflow to be reloaded from the database on their next iteration.

Parameters
namethe name of the workflow to reset
versionthe version of the workflow to reset; if no version string is passed, then all versions of the specified workflow are purged from the workflow cache.
Returns
a string confirming the workflow(s) deleted from the cache
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_EXEC_CONTROL, or OMQ::QR_RESET_WORKFLOW

◆ omq.system.retry-workflow-instance()

hash omq.system.retry-workflow-instance ( softstring  wfiid)

retries the given workflow order instance

In order to make a retry; the workflow order status must be OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry

Parameters
wfiidthe workflow_instanceid to retry
Returns
a hash with the following keys:
  • steps_updated: (deprecated) always 0 in this version of Qorus
  • segments_updated: the number of segments updated
  • workflow_updated: always True in this version of Qorus
  • workflow_status: always OMQ::StatRetry in this version of Qorus
  • cached: True if the workflow data is currently cached
Exceptions
STATUS-ERRORworkflow data does not have OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry status
SESSION-ERRORcannot change status for workflow data managed by another Qorus instance (foreign session ID)
RETRY-ERRORinvalid workflow instance ID
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
See also
omq.system.retry-workflow-instances()

◆ omq.system.retry-workflow-instances()

hash omq.system.retry-workflow-instances ( softlist  l)

retries the given workflow order instances

In order to make a retry; the workflow order status must be OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry

Parameters
la list of workflow_instanceids to retry
Returns
a hash where the top level key is the workflow_instanceid, and the value is either an exception string (indicating that the operation failed) or a hash with the following keys:
  • steps_updated: (deprecated) always 0 in this version of Qorus
  • segments_updated: the number of segments updated
  • workflow_updated: always True in this version of Qorus
  • workflow_status: always OMQ::StatRetry in this version of Qorus
  • cached: True if the workflow data is currently cached
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RETRY_WORKFLOW_ORDER
See also
omq.system.retry-workflow-instance()
Since
Qorus 2.5.1.p7

◆ omq.system.rotate-log-files()

string omq.system.rotate-log-files ( )

Rotates all system log files.

The number of old log files kept is controlled by system option qorus.max-log-files

Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_ROTATE_LOG_FILES or OMQ::QR_LOGGER_CONTROL

◆ omq.system.runtime-properties()

hash omq.system.runtime-properties ( )

Returns a hash with runtime properties specified with -D in the Qorus system startup command-line.

Returns
a hash with runtime properties specified with -D in the Qorus system startup command-line
Since
Qorus 2.5.0

◆ omq.system.schema.refresh-snapshots()

hash omq.system.schema.refresh-snapshots ( )

Refresh helper database snapshots.

Returns
a hash giving a result of the operation in the form (snapshot name: result message)
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SCHEMA_CONTROL
Since
Qorus 2.6.3

◆ omq.system.search-errors()

* hash omq.system.search-errors ( softlist  l)

searches for error definitions at all levels for the given error(s)

Parameters
lone or more error strings to search for
Returns
a hash keyed by the error name, where each value is a hash with the following optional keys:
  • global: an optional hash giving the global error definition (if any)
  • workflow: an optional hash of workflow IDs where each value is an error definition
Note
If RBAC is enabled, then any workflows that the user does not have access to will be filtered from the search results
Since
Qorus 2.8.0

◆ omq.system.service.[servicename].[method]()

any omq.system.service.[servicename].[method] ( )

calls a system service method and returns the result

The service is loaded and started if necessary

Returns
the result of calling the system service method
Exceptions
SERVICE-ERRORinvalid method call; missing method name
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CALL_SYSTEM_SERVICES_RW (for methods with the write flag set) or OMQ::QR_CALL_SYSTEM_SERVICES_RO

◆ omq.system.set-option()

string omq.system.set-option ( hash  params)

sets one or more system options

if any errors occur, an exception is thrown with error information, but all other options will be processed and set

Parameters
paramskey-value pairs where the key names are system option names
Returns
"OK"
Exceptions
OPTION-ERRORinvalid or locked option
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_OPTION_CONTROL
See also
OMQ::omq_option_hash for valid options

◆ omq.system.set-order-info()

nothing omq.system.set-order-info ( softstring  wfiid,
hash  h 
)

Sets or clears additional info for the given workflow order data instance.

Deprecated:
This function is present for backwards-compatibility and uses Order Instance Notes

If a key is present in the hash, but has no value, then the associated value is cleared; no change is made for keys not present in the hash

Parameters
wfiidthe workflow instance id
ha hash with the following keys:
  • op_username: the username of the operator working on the order
  • op_comment: notes about processing the order
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_ORDER_INFO
Since
Qorus 2.5.0

◆ omq.system.set-order-note()

nothing omq.system.set-order-note ( softstring  wfiid,
string  notestr 
)

Add new Order Instance Notes.

Some additional information are attached automatically - username, date of creation etc.

Parameters
wfiidthe workflow_instanceid of the workflow order to update
notestrstring, a text note
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_ORDER_INFO
Since
Qorus 3.0.2

◆ omq.system.set-service-autostart()

string omq.system.set-service-autostart ( string  name,
softstring  stat 
)

Sets the autostart status of the given system service.

Parameters
namethe name of the system service
statthe autostart status for the service (parsed with parse_boolean())
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SET_SERVICE_AUTOSTART

◆ omq.system.set-service-options()

string omq.system.set-service-options ( string  name,
hash  hash 
)

Sets the options given in the hash on the given service.

Options set override the system options of the same name. Only system options valid for services may be set. The service is loaded and initialized if not already loaded. If an exception is thrown due to an option error, all other options will still be set.

Parameters
namethe name of the system service to set options on
hashoption-value pairs
Returns
"OK"
Exceptions
SERVICE-ERRORthe given service cannot be loaded (unknown or error initializing the service)
SERVICE-OPTION-ERRORinvalid option
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SET_SERVICE_OPTIONS

◆ omq.system.set-workflow-instance-error()

hash omq.system.set-workflow-instance-error ( softint  wfiid)

Changes a workflow order data instance's status to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting.

If the status is any other status, an exception will be thrown. To set a workflow order data instance with a OMQ::StatWaiting status to OMQ::StatError, set the child workflows to OMQ::StatError first and the parent workflow's status will be updated automatically. When setting a workflow order from OMQ::StatCanceled to OMQ::StatError, outstanding events will be queued and the associated queued event keys will be present in the return value.

Parameters
wfiidthe workflow order data instance ID
Returns
a hash with the following keys:
  • steps_updated: number of steps updated
  • segments_updated: number of segments updated
  • workflow_status: always OMQ::StatError
  • old_status: the old workflow data status
  • queued_detached_segments: number of detached segment events queued
  • queued_subworkflows: number of subworkflow events queued
  • queued_async_messages: number of async events queued
  • queued_sync_events: number of workflow synchronization events queued
  • queued_async_retries: number of async events queued
  • queued_retries: number of retry events queued
  • queued_fixed_retries: number of retry events with a fixed retry time queued
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
See also
omq.system.set-workflow-instance-error()

◆ omq.system.set-workflow-instances-error()

hash omq.system.set-workflow-instances-error ( softlist  l)

Changes a list of workflow order data instances' statuses to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting.

If the status is any other status, an exception will be thrown. To set a workflow order data instance with a OMQ::StatWaiting status to OMQ::StatError, set the child workflows to OMQ::StatError first and the parent workflow's status will be updated automatically. When setting a workflow order from OMQ::StatCanceled to OMQ::StatError, outstanding events will be queued and the associated queued event keys will be present in the return value.

Parameters
la list of workflow order data instance IDs to set to OMQ::StatError
Returns
a hash where the top-level keys are workflow_instanceids and the value is either an exception string (indicating that the operation failed for that workflow instance ID) or a hash with the following keys:
  • steps_updated: number of steps updated
  • segments_updated: number of segments updated
  • workflow_status: always OMQ::StatError
  • old_status: the old workflow data status
  • queued_detached_segments: number of detached segment events queued
  • queued_subworkflows: number of subworkflow events queued
  • queued_async_messages: number of async events queued
  • queued_sync_events: number of workflow synchronization events queued
  • queued_async_retries: number of async events queued
  • queued_retries: number of retry events queued
  • queued_fixed_retries: number of retry events with a fixed retry time queued
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_WORKFLOW_ORDER_ERROR
Since
Qorus 2.5.1.p7
See also
omq.system.set-workflow-instance-error()

◆ omq.system.set-workflow-option()

string omq.system.set-workflow-option ( softint  id,
hash  hash 
)

Sets the options given in the hash on the running workflow identified by the execution ID passed.

If the workflow has an option list and any of the options are not valid for that workflow, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.

Parameters
idthe workflow execution ID to set options on
hashoption-value pairs
Returns
a string confirming that the options have been set
Exceptions
INVALID-WORKFLOW-EXECUTION-IDinvalid workflow execution ID
WORKFLOW-OPTION-ERRORinvalid option for workflow or option cannot be overridden at the workflow level
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_EXEC_CONTROL, or OMQ::QR_WORKFLOW_OPTION_CONTROL
  • workflow options are now actually global for the given workflow; this API takes an execution instance ID, but the options are still set against the workflow and not just on the execution instance level (global workflow options were implemented in Qorus 3.0.0)
  • workflow options are persistent (persistent workflow options were implemented in Qorus 3.0.0)
Since
Qorus 3.0.0 workflow options are global and persistent

◆ omq.system.show-workflow-cache()

list omq.system.show-workflow-cache ( )

returns a list of the workflows currently cached

Returns
a list of hashes with the following keys:
  • name: (string) the name of the workflow
  • version: (string) the version of the workflow
  • workflowid: (int) the workflow ID of the workflow
  • cached: (date) the date and time the workflow was cached
Note
If RBAC is enabled, then any workflows that the user does not have access to will be filtered from the list returned

◆ omq.system.shutdown()

string omq.system.shutdown ( )

initiates the system shutdown process

This API will start the asynchronous shutdown process in the Qorus system. The response indicates only that the shutdown process has begun, and not that the system has been fully shut down. Check the log file or the process list (‘ps –ef') to verify that the system has completely stopped.

Returns
"OK"
Exceptions
SHUTDOWN-ALREADY-IN-PROGRESSsystem shutdown is already in progress
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SHUTDOWN

◆ omq.system.shutdown-wait()

string omq.system.shutdown-wait ( )

shuts down the system; returns when the system shutdown process is complete

Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SHUTDOWN

◆ omq.system.skip-step()

nothing omq.system.skip-step ( softstring  wfiid,
softstring  stepid,
softint  ind = 0 
)

Skips execution of a step in a workflow.

Sometimes, for reasons outside of a workflow's control, execution for a given step must be skipped, but the rest of the workflow's logic should be executed. This call allows Qorus to continue executing a workflow order data instance after skipping the given step. Only steps with OMQ::StatError, OMQ::StatRetry, OMQ::StatEventWaiting, or OMQ::StatAsyncWaiting can be skipped. Subworkflow steps with any status cannot be skipped; the child workflow must be corrected instead.

Note that this method will also queue internal events for asynchronous steps, and will trigger a retry of the workflow for all other steps to ensure that the workflow is immediately reprocessed.

If several steps should be retried, use omq.system.skip-step-without-retry() on every step except the last one to be retried, as this function will trigger a retry of the entire workflow order data instance.

Parameters
wfiidthe workflow order data instance ID
stepidthe step ID
indthe step index for array steps
Exceptions
SKIP-STEP-ERRORstep is a subworkflow step; step has not been executed in the given workflow order instance; the given workflow instance ID does not exist
STEP-STATUS-ERRORstep status does not allow it to be skipped (ex: IN-PROGRESS, COMPLETE)
SESSION-ERRORworkflow order instance belongs to another Qorus session
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SKIP_STEP

◆ omq.system.skip-step-without-retry()

nothing omq.system.skip-step-without-retry ( softint  wfiid,
softint  stepid,
softint  ind = 0 
)

Skips execution of a step in a workflow without initiating an immediate retry.

Sometimes, for reasons outside of a workflow's control, execution for a given step must be skipped, but the rest of the workflow's logic should be executed. This call allows Qorus to continue executing a workflow order data instance after skipping the given step. Only steps with OMQ::StatError, OMQ::StatRetry, OMQ::StatEventWaiting, or OMQ::StatAsyncWaiting can be skipped. Subworkflow steps with any status cannot be skipped; the child workflow must be corrected instead.

Note that this method will also queue internal events for asynchronous steps.

If several steps should be retried, execute this method on every step except the last one to be retried, as this function will trigger a retry of the entire workflow order data instance. Execute omq.system.skip-step() on the final step to also trigger a retry of the workflow order data after the skipo is marked to be skipped.

Parameters
wfiidthe workflow order data instance ID
stepidthe step ID
indthe step index for array steps
Exceptions
SKIP-STEP-ERRORstep is a subworkflow step; step has not been executed in the given workflow order instance; the given workflow instance ID does not exist
STEP-STATUS-ERRORstep status does not allow it to be skipped (ex: IN-PROGRESS, COMPLETE)
SESSION-ERRORworkflow order instance belongs to another Qorus session
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SKIP_STEP

◆ omq.system.start-listeners()

list omq.system.start-listeners ( softstring  bind,
*string  cert_file,
*string  key_file 
)

starts a new HTTP listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given

Parameters
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
cert_filethe file name of the X.509 certificate in PEM format (only for HTTPS listeners)
key_filethe file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
Returns
a list of hashes for each listener started, each hash having the following keys (note that for UNIX domain socket listeners the hostname, hostname_desc, and port keys will not be present):
  • hostname: the hostname of the interface
  • hostname_desc: a descriptive string for the hostname including the address family (ex: "ipv6[localhost]")
  • address: the address of the listener (i.e. "192.168.30.4", etc)
  • address_desc: a descriptive string for the hostname including the address family (ex: "ipv6[::1]")
  • port: the port number
  • family: an integer giving the address family (AF_INET, AF_INET6, AF_UNIX, etc)
  • familystr: a string describing the address family (ex: "ipv6")
  • proto: either "http" or "https"
  • id: the Qorus ID of the listener
  • bind: a string giving the bind address used (ex: "127.0.0.1:8001")
See also
omq.system.stop-listener()
Since
Qorus 2.6.0
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_START_LISTENER

◆ omq.system.start-workflow()

hash omq.system.start-workflow ( hash  params)

Starts a workflow execution instance with the designated name and version.

If any errors occur, an exception is thrown.

Parameters
paramsa hash with the following keys:
  • name: (string) the name of the workflow; this key must be present
  • version: (string) the version of the workflow; if the version key is not supplied, then the latest version of the workflow is started
  • mode: (string) either OMQ::WM_Normal (the default if no mode key is present) or OMQ::WM_Recovery
  • options: (hash) a hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the workflow execution instance is not started
Returns
a hash with the following keys:
  • id: (int) the execution ID of the workflow execution instance
  • version: (string) the version of the workflow started (useful if no version key supplied in the call)
Exceptions
PARAMETER-ERRORinvalid workflow, mode, or options key in incorrect format (not a hash)
SHUTDOWN-IN-PROGRESScannot start new workflows because the system is shutting down
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
See also
omq.system.start-workflows()

◆ omq.system.start-workflows()

hash omq.system.start-workflows ( hash  params)

Starts one or more workflow execution instances with the designated name and version.

If any errors occur, an exception is thrown

Parameters
paramsa hash with the following keys:
  • name: (string) the name of the workflow; this key must be present
  • instances: (int) number of execution instances to start; must be > 0
  • version: (string) the version of the workflow; if the version key is not supplied, then the latest version of the workflow is started
  • mode: (string) either OMQ::WM_Normal (the default if no mode key is present) or OMQ::WM_Recovery
  • options: (hash) a hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the workflow execution instance is not started
Returns
a hash with the following key:
  • id: (list of int) the execution IDs of the workflow execution instances started
  • version: (string) the version of the workflows started (useful if no version key supplied in the call)
Exceptions
PARAMETER-ERRORinvalid workflow, mode, options key in incorrect format (not a hash), or invalid number of instances
SHUTDOWN-IN-PROGRESScannot start new workflows because the system is shutting down
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_EXEC_CONTROL, or OMQ::QR_START_WORKFLOW
See also
omq.system.start-workflow()

◆ omq.system.stop-all-workflows()

string omq.system.stop-all-workflows ( )

stops all running workflows

On errors, an exception is thrown

Returns
a string describing the number of workflows being stopped
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

◆ omq.system.stop-listener()

nothing omq.system.stop-listener ( softstring  name)

stops the listener from the bind address

Parameters
namethe name or bind address of the listener to stop
Exceptions
INVALID-LISTENER-ERRORinvalid name or bind address, cannot stop last listener
See also
omq.system.stop-listener-id()
Since
Qorus 2.6.0
Note

◆ omq.system.stop-listener-id()

nothing omq.system.stop-listener-id ( softint  id)

stops the listener from listener ID

Parameters
idthe ID listener to stop
Exceptions
INVALID-LISTENER-ERRORinvalid listener ID, cannot stop last listener
See also
omq.system.stop-listener()
Since
Qorus 2.6.0
Note

◆ omq.system.stop-workflow()

string omq.system.stop-workflow ( string  name,
*string  version 
)

stops all instances of the given workflow

On errors, an exception is thrown

Parameters
namethe name of the workflow to stop
versionthe optional version of the workflow to stop; if this parameter is not passed, then all versions of the given workflow are stopped
Returns
a string describing the number of workflows being stopped
Exceptions
PARAMETER-ERRORno instances of the given workflow are running
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

◆ omq.system.stop-workflow-instance()

string omq.system.stop-workflow-instance ( softint  id)

stops the given workflow execution instance given its ID

On errors, an exception is thrown

Parameters
idthe execution instance ID of the workflow execution instance to stop
Returns
a string confirming that the workflow is stopping
Exceptions
INVALID-WORKFLOW-EXECUTION-IDinvalid workflow execution ID
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
STOP-ERRORworkflow is already stopping; cannot stop workflow if called from within the workflow to be stopped
Note

◆ omq.system.submit-data.[workflow].[version]()

hash omq.system.submit-data.[workflow].[version] ( hash  params,
string  status = OMQ::StatReady 
)

create workflow order (workflow order data instance)

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

Parameters
paramsThe hash passed must have at either a staticdata key or an external_order_instanceid key, valid keys:
  • staticdata: the static data for the order
  • external_order_instanceid: the external order instance ID for the workflow data
  • dynamicdata: the initial dynamic data for the order
  • orderkeys: a hash of order keys for the order
  • scheduled: 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
  • priority: the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • parent_workflow_instanceid: a loosely-coupled workflow that will be marked as the parent of this workflow
statuscreate the workflow order data instance with this status; may be either:
Returns
a hash with the following key:
  • workflow_instanceid the workflow instance ID of the workflow order instance ID created
Exceptions
SUBMIT-ORDER-ERRORunknown workflow, invalid status
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SUBMIT_ORDER
See also
omq.system.create-order()

◆ omq.system.update-current-user()

string omq.system.update-current-user ( hash  hash)

Modifies the current user in the database and in the RBAC cache.

Parameters
hasha hash giving the information to update, valid keys are as follows:
  • pass: (string) password
  • name: (string) user descriptive (or real) name
  • roles: (list of strings) the new list will replace the current list
  • storage: (hash) updated key-value pairs for server-side user storage; set a key to NOTHING to delete the key
See also
omq.system.update-user() for full description of the hash
Returns
"OK"
Exceptions
UPDATE-USER-ERRORno authentication information supplied in call
RBAC-UPDATE-USER-ERRORno valid keys in hash, invalid permission, invalid group
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_USER to update permissions, name, or groups

◆ omq.system.update-global-error()

string omq.system.update-global-error ( hash  eh)

creates or updates a global error

Error definitions are committed internally and also to the database in this method (i.e. all changes are persistent)

Parameters
ehan error hash with the following keys:
  • "error": the name of the error
  • "description": the description of the error
  • "severity": (optional) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • "retry_flag": (optional, deprecated) a boolean retry flag value (if not present then False is assumed); this key is deprecated by status and is present only for backwards compatibility; at most one of retry_flag and status must be present; the mapping from retry_flag to status is True to OMQ::StatRetry and False to OMQ::StatError
  • "status" : (optional) the status the order enters when this error appears (OMQ::StatError, OMQ::StatRetry, OMQ::StatCanceled); at most one of retry_flag and status must be present
  • "business_flag": (optional) a boolean business flag value (if not present then False is assumed)
  • "retry_delay_secs": (optional) an optional retry value in seconds (only used if status is OMQ::StatRetry)
Returns
a string giving the result of the operation; one of:
  • "UPDATED-GLOBAL": the existing global error was updated
  • "CREATED-GLOBAL": a new global error was created
  • "UNCHANGED-GLOBAL": the new definition is identical to the old definition
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
ERROR-UPDATE-ERRORwhen the arguments are invalid
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
Since
Qorus 2.8.0

◆ omq.system.update-permission()

string omq.system.update-permission ( string  permission,
string  desc 
)

Modifies the description for an existing user permission in the database and in the RBAC cache.

System permissions may not be updated; only user permissions may be updated.

Parameters
permissionthe permission to update
descthe new description of the permission
Returns
"OK"
Exceptions
RBAC-UPDATE-PERMISSION-ERRORinvalid permission
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_PERMISSION

◆ omq.system.update-role()

string omq.system.update-role ( string  name,
hash  h 
)

Modifies an existing role in the database and in the RBAC cache.

Parameters
namethe role to update
ha hash giving the information to update, valid keys are as follows:
  • desc: (string) role description
  • perms: (list of strings) the new list will replace the current list unless the permission names are preceded by "+" or "-", meaning add or remove a permission, respectively (in which case all permissions must be preceded by a "+" or "-"; note that "permissions" is also accepted for backwards-compatibility); note that empty list means revoking all permissions from the role
  • groups: (list of strings) the new list will replace the current list unless the group names are preceded by "+" or "-", meaning add or remove a group, respectively (in which case all group names must be preceded by a "+" or "-"); note that empty list means deleting all groups from the role
Returns
"OK"
Exceptions
RBAC-UPDATE-ROLE-ERRORinvalid role, no valid keys in hash, invalid permission, invalid group
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_ROLE

◆ omq.system.update-user()

string omq.system.update-user ( string  user,
hash  hash 
)

Modifies an existing user in the database and in the RBAC cache.

Parameters
userthe username to update
hasha hash giving the information to update, valid keys are as follows:
  • pass: (string) password
  • name: (string) user description
  • storage: (hash) updated key-value pairs for server-side user storage; set a key to NOTHING to delete the key
  • roles: (list of strings) the new list will replace the current list unless the role names are preceded by "+" or "-", meaning add or remove a role, respectively (in which case all role names must be preceded by a "+" or "-"); note that if the key is present then empty list or string means revoking all roles from the user
Returns
"OK"
Exceptions
RBAC-UPDATE-USER-ERRORinvalid user, no valid keys in hash, invalid role
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_USER

◆ omq.system.update-workflow-error()

string omq.system.update-workflow-error ( softint  wfid,
hash  eh,
*bool  forceworkflow 
)

creates or updates a workflow-specific error definition

Error definitions are committed internally and also to the database in this method (i.e. all changes are persistent)

Parameters
wfidthe workflow ID of the workflow to update
ehan error hash with the following keys:
  • "error": the name of the error
  • "description": the description of the error
  • "severity": (optional) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • "retry_flag": (optional, deprecated) a boolean retry flag value (if not present then False is assumed); this key is deprecated by status and is present only for backwards compatibility; at most one of retry_flag and status must be present; the mapping from retry_flag to status is True to OMQ::StatRetry and False to OMQ::StatError
  • "status" : (optional) the status the order enters when this error appears (OMQ::StatError, OMQ::StatRetry, OMQ::StatCanceled); at most one of retry_flag and status must be present
  • "business_flag": (optional) a boolean business flag value (if not present then False is assumed)
  • "retry_delay_secs": (optional) an optional retry value in seconds (only used if status is OMQ::StatRetry)
forceworkflowif True then error processing will only be made on the workflow level regardless of any global error of the same name
Returns
a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
  • "CREATED-GLOBAL": a new global error was created
  • "UNCHANGED-GLOBAL": the new global definition is identical to the old definition
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
WORKFLOW-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
ERROR-UPDATE-ERRORwhen the arguments are invalid
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
Since
Qorus 2.8.0

◆ omq.system.wait-for-events()

hash omq.system.wait-for-events ( softint  min_id,
*timeout  timeout_ms 
)

Returns a hash giving the list of the new events and the last event ID generated by the system.

A required argument must be supplied giving the minimum event ID to return; an optional argument may be passed giving a timeout in milliseconds to wait for new events. This API is suitable for unconditional event polling.

Parameters
min_idthe minimum event ID to return; events will only be returned with an event ID at least as large as this value
timeout_msa optional timeout in milliseconds; if this value is not present or zero then the function returns immediately
Returns
a hash with the following keys:
  • lastid: the highest existing event ID in the system at the time the results were returned
  • events: a list of event hashes; this key will not be present if there are no events available
  • shutdown: if this key is returned, it means the system is shutting down
See also
Since
Qorus 2.0.2
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.system.wait-for-events-and()

hash omq.system.wait-for-events-and ( softint  min_id,
*softlist  criteria,
*timeout  timeout_ms,
*softlist  or_not,
*softlist  nfilt 
)

return system events that meet all of the given criteria or none of the optional "or not" criteria

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
criteriathis argument is the criteria list for “logical and” comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure “logical and” behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the function returns immediately
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system's event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted “logical or” logic, the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
nfiltthis argument is an optional criteria list which will filter out elements matched by the above rules; if any event matched by the above rules then matches all the hash values in any of the elements of this list, then it's filtered out of the result list
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the function returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
See also
Since
Qorus 2.0.2, Qorus 3.0 added the nfilt argument
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.system.wait-for-events-or()

hash omq.system.wait-for-events-or ( softint  min_id,
*softlist  criteria,
*timeout  timeout_ms,
*softlist  and_not,
*softlist  nfilt 
)

return system events that meet any of the given criteria and none of the optional "and not" criteria

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
criteriathis argument is the criteria list for “logical or” comparisons to be applied to the events. If a system event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional fourth argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure “logical or” behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the function returns immediately
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure “logical and” filtering the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
nfiltthis argument is an optional criteria list which will filter out elements matched by the above rules; if any event matched by the above rules then matches all the hash values in any of the elements of this list, then it's filtered out of the result list
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the function returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
See also
Since
Qorus 2.0.2, Qorus 3.0 added the nfilt argument
Bug:
these service methods are not filtered for the calling user's Interface Groups membership when called externally

◆ omq.user.delete-service()

string omq.user.delete-service ( string  name,
*string  version 
)

Unloads the named user service from the system.

If the service is running, it is first stopped. Additionally, any outstanding method calls must return before the service can be unloaded.

Parameters
namethe name of the user service to unload
versionthe version of the service to unload; normally this parameter should not be given; only one version of a service can be loaded at a time and giving the wrong version string will cause an exception to be thrown
Returns
"OK"
Note
does not delete any data from the system database schema; only unloads the service from memory
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
SERVICE-NOT-LOADEDthis exception is thrown when the service is not loaded
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_UNLOAD_SERVICE

◆ omq.user.get-service-autostart()

bool omq.user.get-service-autostart ( string  name)

returns the autostart status of the given user service

Parameters
namethe name of the user service
Returns
the autostart status
Exceptions
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

◆ omq.user.get-service-options()

any omq.user.get-service-options ( string  name)

Returns options set on the given unsert service; the service must be already loaded or an exception is raised.

If no arguments are passed, then all options are returned, otherwise only the values for the given options are returned. If the given option is not overridden on the service level, then the value of the system option is returned. If the service is not already loaded is not valid, then an exception is raised

Parameters
namethe service name
Returns
a single value if only a single option is requested, a hash of options if nore than one option is requested; note that the value for the option returned may by NOTHING if the given option is not set at the service level
Exceptions
SERVICE-ERRORthe given service is not loaded
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

◆ omq.user.list-services()

list omq.user.list-services ( )

returns a list of all user services currently loaded

Returns
a list of all currently loaded user services; each element is a hash with the following keys:
  • type: "user"
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • log: log file path
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True of False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
    • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
    • desc: a hashdecl description of the resource
    • info: a hash with additional, free-form information about the resource
  • groups: a list of interface group names that this service is a member of
Note
if RBAC is enabled and the user does not have access to all user services, only the user services the user has access to will be reported in the list returned.
Since
2.6.3.p17 added the "log" key to the return hash

◆ omq.user.reset-service()

bool omq.user.reset-service ( string  name,
bool  load = False 
)

unloads a single user service and reloads it from the database

Parameters
namethe name of the user service to reset
loadif True then the service will be loaded and initialized if it was not already loaded
Returns
True if the service was already loaded before this call, False if not
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also
Since
Qorus 2.6.0

◆ omq.user.reset-services()

list omq.user.reset-services ( )

unloads all user services currently loaded in memory and reloads those services from the database

If the calling user has restricted access to user services, only services visible by the current user are reset.

Returns
list of hashes of services reset with the following keys:
  • type: always "user" with this call
  • name: name of the service
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also
Since
Qorus 2.6.0

◆ omq.user.service.[servicename].[method]()

any omq.user.service.[servicename].[method] ( )

calls a user service method and returns the result

The service is loaded and started if necessary

Returns
the result of calling the user service method
Exceptions
SERVICE-ERRORinvalid method call; missing method name
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_CALL_USER_SERVICES_RW (for methods with the write flag set) or OMQ::QR_CALL_USER_SERVICES_RO

◆ omq.user.set-service-autostart()

string omq.user.set-service-autostart ( string  name,
softstring  stat 
)

Sets the autostart status of the given user service.

Parameters
namethe name of the user service
statthe autostart status for the service (parsed with parse_boolean())
Returns
"OK"
Exceptions
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SET_SERVICE_AUTOSTART

◆ omq.user.set-service-options()

string omq.user.set-service-options ( string  name,
hash  hash 
)

Sets the options given in the hash on the given service.

Options set override the user options of the same name. Only system options valid for services may be set. The service is loaded and initialized if not already loaded. If an exception is thrown due to an option error, all other options will still be set.

Parameters
namethe name of the user service to set options on
hashoption-value pairs
Returns
"OK"
Exceptions
SERVICE-ERRORthe given service cannot be loaded (unknown or error initializing the service)
SERVICE-OPTION-ERRORinvalid option
AUTHORIZATION-ERRORthis exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
SERVICE-ACCESS-ERRORthis is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SET_SERVICE_OPTIONS