Introduction to the Qorus Service API

This section describes additional classes, constants, and functions that are imported into service Program objects by the Qorus system itself that make up the Qorus Service API.

Service Program Container

Each Qorus service has a single Qore Program object containing all its code for the step, array, validation, async end functions, as well as any objects imported into the Program object (classes, constants, and functions listed as attributes of the service when the service is defined).

Service Program objects are restricted from using elements of the Qore Language related to process and thread control; the use of these functions is either dangerous or could violate the integrity of the Qorus server process and therefore is restricted.

To enforce these restrictions, service Program objects are created with the following parse restrictions:

Please see the above links for more information on the features made unavailable when these parse options are set.

Please note that despite these restrictions, service program objects have most of the Qore language API and class library available for use.

Furthermore, the following parse defines are defined:

"Qorus" (common to workflows, services, and jobs)
"QorusServer" (common to workflows, services, and jobs)
"QorusHasUserConnections" (common to workflows, services, and jobs)
"QorusHasAlerts" (common to workflows, services, and jobs)
"QorusService" (service-specific)
"QorusHasHttpUserIndex" (service-specific)
all defines set in defines (common to workflows, services, and jobs)

Global Variables

Services may declare global variables, but because the %no-top-level parse restriction is set for the Program object; they may not be initialized at the top level of the program.

Initialize them in the init() method instead; global variables may also be declared here if desired. Global variables may be declared anywhere in the Program object; they do not have to be declared at the top level of the service program.

Service API Overview

This section will list all of the functions specific to service programs.

See also: Qorus Common Server API for APIs and API concepts common to all Qorus server code (workflows, services, and jobs).; Qorus Common API for a definition of API definitions common to all Qorus user code (workflows, services, and jobs) as well as the client library.

Note that service-specific API functions are found in the OMQ::UserApi::Service namespace and are prefixed by "svc_" for consistency's sake and ease of identification.

Logging Function

(common API function):

log()

Service Resource Functions

RBAC Functions

SOAP Functions

svc_get_soap_call_context()
svc_register_soap_handler()

Local HTTP and UI Functions

FTP Functions

svc_bind_ftp()

Event Handling Functions

Miscellaneous Service API Functions

Deprecated Service API Functions

registerSoapService(): use svc_register_soap_handler() instead
get_omq_option(): use get_option() instead

Backwards-Compatible Functions

Old backwards-compatible service API functions (will be maintained indefinitely for backwards compatibility):

bind_ftp(): replaced with svc_bind_ftp()
bind_handler(): replaced with svc_bind_handler()
bind_http(): replaced with svc_bind_http()
call_api_as_current_user(): replaced with svc_call_api_as_current_user()
check_authorization(): replaced with svc_check_authorization()
check_authorization_or(): replaced with svc_check_authorization_or()
check_job_access(): replaced with svc_check_job_access()
check_job_instance_access(): replaced with svc_check_job_instance_access()
check_queue_access(): replaced with svc_check_queue_access()
check_service_access(): replaced with svc_check_service_access()
check_workflow_access(): replaced with svc_check_workflow_access()
check_workflow_instance_access(): replaced with svc_check_workflow_instance_access()
get_active_jobs_as_current_user(): replaced with svc_get_active_jobs_as_current_user()
get_call_context(): replaced with svc_get_call_context()
get_job_access_hash(): replaced with svc_get_job_access_hash()
get_job_access_list(): replaced with svc_get_job_access_list()
get_last_events(): replaced with svc_get_last_events()
get_last_events_and(): replaced with svc_get_last_events_and()
get_last_events_or(): replaced with svc_get_last_events_or()
get_resource(): replaced with svc_get_resource()
get_resource_data(): replaced with svc_get_resource_data()
get_resource_hash(): replaced with svc_get_resource_hash()
get_resource_list(): replaced with svc_get_resource_list()
get_template_hash(): replaced with svc_get_template_hash()
get_template_list(): replaced with svc_get_template_list()
get_running_workflow_list_as_current_user(): replaced with svc_get_running_workflow_list_as_current_user()
get_service_access_hash(): replaced with svc_get_service_access_hash()
get_service_access_list(): replaced with svc_get_service_access_list()
get_workflow_access_hash(): replaced with svc_get_workflow_access_hash()
get_workflow_access_list(): replaced with svc_get_workflow_access_list()
getServiceInfo(): replaced with svc_get_service_info()
get_service_info_as_current_user(): replaced with svc_get_service_info_as_current_user()
getSoapCallContext(): replaced with svc_get_soap_call_context()
has_resource(): replaced with svc_has_resource()
has_template(): replaced with svc_has_template()
render_template(): replaced with svc_render_template()
registerSoapHandler(): replaced with svc_register_soap_handler()
startServiceThread(): replaced with svc_start_thread()
startServiceThreadArgs(): replaced with svc_start_thread_args()
test_authorization(): replaced with svc_test_authorization()
test_authorization_or(): replaced with svc_test_authorization_or()
test_workflow_access(): replaced with svc_test_workflow_access()
test_service_access(): replaced with svc_test_service_access()
test_job_access(): replaced with svc_test_job_access()
try_get_resource(): replaced with svc_try_get_resource()
try_get_resource_data(): replaced with svc_try_get_resource_data()
try_render_template(): replaced with svc_try_render_template()
ui_extension_register(): replaced with svc_ui_extension_register()
wait_for_events(): replaced with svc_wait_for_events()
wait_for_events_and(): replaced with svc_wait_for_events_and()
wait_for_events_or(): replaced with svc_wait_for_events_or()

Event Processing

Each event hash has the the following keys:

id (int): the unique event ID for the application session; the first event starts with 1 and increases serially with each event
time (date): the date and time the event was submitted with a resolution to the microsecond
timeus (int): the microsecond value of the event (i.e. 0-999); this value is included separately because when the date and time are serialized through some protocols (such as XML-RPC), then microsecond value is lost
class (int): the event class code of the event
classstr (string): the string designation corresponding to the event class code (see the keys of the OMQ::QE_RMAP_CLASS Constant Hash for possible values)
event (int): the event code for the event
eventstr (string): the string designation corresponding to the event code (see the keys of the OMQ::QE_RMAP_EVENT Constant Hash for possible values)
severity (int): the severity level of the event; please note that all user events will have severity code 0 (OMQ::ES_Info). Values may be integers from -1 to 4 corresponding to the keys in the OMQ::ErrorSeverityMap hash.
severitystr (string): the string corresponding to the severity level; see the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field.
caller (hash): a hash of caller information in case the event was trigger by or can be traced directly to an external call
compositeseverity (int) the maximum of the system and user severity levels; in case there is no user severity level; then this field is always equal to the system severity level. Values may be integers from -1 to 4 corresponding to the keys in the OMQ::ErrorSeverityMap hash.
compositeseveritystr (string): the string corresponding to the composite severity level; see the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field
userseverity (integer, optional): in case the event is a user event and a user severity level was supplied; this field contains the severity level of the user event
userseveritystr (string, optional): in case the event is a user event and a user severity level was supplied; this field contains the string corresponding to the user severity level; see the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field
info (hash, optional): additional event-specific information; See Event Information Descriptions for details on each message; note that user events have user-defined information in this field

Event Information Descriptions

This section contains the definitions of the info hash of event types

WORKFLOW_START Event Information Description

Event constant: OMQ::QEC_WORKFLOW_START

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
execid: The workflow execution ID
mode: The mode of the workflow (OMQ::WM_Normal, OMQ::WM_Recovery, OMQ::WM_Synchronous)
synchronous: True for synchronous workflows, False if not
options: A hash of workflow options

WORKFLOW_STOP Event Information Description

Event constant: OMQ::QEC_WORKFLOW_STOP

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
execid: The workflow execution ID
mode: The mode of the workflow (OMQ::WM_Normal, OMQ::WM_Recovery, OMQ::WM_Synchronous))
synchronous: True for synchronous workflows, False if not

WORKFLOW_CACHE_RESET Event Information Description

Event constant: OMQ::QEC_WORKFLOW_CACHE_RESET

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)

WORKFLOW_DATA_SUBMITTED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_SUBMITTED

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
status: The new workflow order instance's initial status (see Workflow, Segment, and Step Status Descriptions for possible status values)

WORKFLOW_INFO_CHANGED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_INFO_CHANGED

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
info: The info hash for the change

WORKFLOW_STATUS_CHANGED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_STATUS_CHANGED

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
info: A hash with old and new keys giving the old and new status values (see Workflow, Segment, and Step Status Descriptions for possible status values)

WORKFLOW_DATA_ERROR Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_ERROR

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
execid: The workflow execution ID
error: A hash of error information containing the following keys:
- err: the error string (ex: exception name)
- desc: the error description (ex: exception description)
- info: any additional error information provided
- business_error: True for business errors, False if not
- stepid: the stepid of the error, if any
- ind: the ind code of the step (array index), if any
- retry: retry number for error
- errorid: the error_instanceid in the database

WORKFLOW_DATA_RELEASED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_RELEASED

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
status: The status of the workflow as it is released
business_error: The business error status of the workflow (True only if the status is OMQ::StatError due to a business error)

WORKFLOW_DATA_CACHED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_CACHED

name: The name of the workflow
version: The version of the workflow
workflowid: The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
workflow_instanceid: The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
status: The status of the workflow as it is released
business_error: The business error status of the workflow (True only if the status is OMQ::StatError due to a business error)
external_order_instanceid: The external order instance ID of the workflow, if any
keys: A hash of workflow order keys, if any

SERVICE_START Event Information Description

Event constant: OMQ::QEC_SERVICE_START

type: The type of service; either USER or SYSTEM
name: The name of the service
version: The version of the service
serviceid: The service ID (metadata ID, i.e. services.serviceid in the database)

SERVICE_STOP Event Information Description

Event constant: OMQ::QEC_SERVICE_STOP

type: The type of service; either USER or SYSTEM
name: The name of the service
version: The version of the service
serviceid: The service ID (metadata ID, i.e. services.serviceid in the database)

SERVICE_ERROR Event Information Description

Event constant: OMQ::QEC_SERVICE_ERROR

type: The type of service; either USER or SYSTEM
name: The name of the service
version: The version of the service
serviceid: The service ID (metadata ID, i.e. services.serviceid in the database)
err: The error code for the error
desc: The error description
info: Additional information for the error, if available

JOB_START Event Information Description

Event constant: OMQ::QEC_JOB_START

name: The name of the job
version: The version of the job
jobid: The job ID (metadata ID, i.e. jobs.jobid in the database)
info: Additional information about the job; a hash with the following keys:
- description: the job's description
- single_instance: boolean flag, True if the job can only be run on one instance at a time on the same schema
- run_skipped: boolean flag, True if the job will be run immediately if its last trigger time was missed due to the system being down
- last_executed: date/time of last execution
- next: next trigger date/time
- trigger: a string describing the job's trigger

JOB_STOP Event Information Description

Event constant: OMQ::QEC_JOB_STOP

name: The name of the job
version: The version of the job
jobid: The job ID (metadata ID, i.e. jobs.jobid in the database)

JOB_INSTANCE_START Event Information Description

Event constant: OMQ::QEC_JOB_INSTANCE_START

name: The name of the job
version: The version of the job
jobid: The job ID (metadata ID, i.e. jobs.jobid in the database)
job_instanceid: The job instance ID (i.e. job_instance.job_instanceid in the database)

JOB_INSTANCE_STOP Event Information Description

Event constant: OMQ::QEC_JOB_INSTANCE_STOP

name: The name of the job
version: The version of the job
jobid: The job ID (metadata ID, i.e. jobs.jobid in the database)
job_instanceid: The job instance ID (i.e. job_instance.job_instanceid in the database)
status: the job instance's final status in the database (see Job Data Status Codes for possible values)

JOB_ERROR Event Information Description

Event constant: OMQ::QEC_JOB_ERROR

name: The name of the job
version: The version of the job
jobid: The job ID (metadata ID, i.e. jobs.jobid in the database)
job_instanceid: The job instance ID (i.e. job_instance.job_instanceid in the database)
error: a hash of error information with the following keys:
- err: the error code
- desc: the description of the error
- info: optional info about the error
- business_error: boolean flag, True if the error is a business error
- errorid: the error instance id for the job (i.e. job_errors.job_errorid in the database)

GROUP_STATUS_CHANGED Event Information Description

Event constant: OMQ::QEC_GROUP_STATUS_CHANGED

name: the interface group's name
enabled: the new status of the group

ALERT_ONGOING_RAISED Event Information Description

Event constant: OMQ::QEC_ALERT_ONGOING_RAISED

type: the alert type
id: the ID of the object causing or related to the alert
alert: the string "name" of the alert
reason: the text giving the reason for the alert
name: the name of the object causing or related to the alert
version: the version of the object causing or related to the alert

ALERT_ONGOING_CLEARED Event Information Description

Event constant: OMQ::QEC_ALERT_ONGOING_CLEARED

type: the alert type
id: the ID of the object causing or related to the alert
alert: the string "name" of the alert
reason: the text giving the reason for the alert
name: the name of the object causing or related to the alert
version: the version of the object causing or related to the alert

ALERT_TRANSIENT_RAISED Event Information Description

Event constant: OMQ::QEC_ALERT_TRANSIENT_RAISED

type: the alert type
id: the ID of the object causing or related to the alert
alert: the string "name" of the alert
reason: the text giving the reason for the alert
name: the name of the object causing or related to the alert
version: the version of the object causing or related to the alert

Event Filter Criteria

The following gives a list of the criteria that can be used for filtering events:

"all": The argument with this criteria is ignored; automatically matches all events; this criteria is useful with “logical or” filtering and an “and not” list to specify all events except events matching all of the criteria in any of the “and not” criteria hashes.
"class": The class code for the event; the event’s class code must match this class code exactly for the criteria to match
"classstr": The string designation corresponding to the event class code (see the keys of the OMQ::QE_RMAP_CLASS Constant Hash for possible values); the event’s class string must match this class string exactly for the criteria to match
"event": The event code for the event; the event’s event code must match this event code exactly for the criteria to match
"eventstr": The string designation corresponding to the event code (see the keys of the OMQ::QE_RMAP_EVENT Constant Hash for possible values); the event’s event string must match this event string exactly for the criteria to match
"mincompositeseverity": The minimum composite severity code for the event. Composite severity is the maximum of the event and user severity levels. Values may be integers from -1 to 4 corresponding to the keys in the OMQ::ErrorSeverityMap hash. If the event has an equal or higher composite severity code, then this criteria matches.
"mincompositeseveritystr": The string description corresponding to the minimum composite severity code for the event. Composite severity is the maximum of the event and user severity levels. See the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field. When the strings are converted to severity codes, works like the mincompositeseverity criteria.
"minseverity": The minimum severity code for the event; values may be integers from -1 to 4 corresponding to the keys in the OMQ::ErrorSeverityMap hash. If the event has an equal or higher severity code, then this criteria matches.
"minseveritystr": The string description corresponding to the minimum severity code for the event; see the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field. When the strings are converted to severity codes, works like the minseverity criteria.
"miuserseverity": The minimum user severity for the event; values may be integers from -1 to 4 corresponding to the keys in the OMQ::ErrorSeverityMap hash. If the event has an equal or higher user severity code, then this criteria matches.
"minuserseveritystr": The string description corresponding to the minimum user severity code for the event; see the keys of the OMQ::ErrorSeverityOrder hash for possible values of this field. When the strings are converted to severity codes, works like the minuserseverity criteria.
"none": The argument with this criteria is ignored; automatically matches no events; this criteria is useful with “logical and” filtering” and an “or not” list to specify all events except those not matching the criteria in the “or not” list.

Qorus Integration Engine