Qorus Integration Engine®  4.0.3.p1_git
Service API Reference

Table of Contents

Introduction to the Qorus Service API

Each service's Program container is set up with the following imported objects:

In addition to the above, all public constants in the OMQ namespace are available.

See also
Implementing Services

Service Class API

The service class APIs are documented here:

For class-based services, the service's implementation class must inherit Service::QorusService (Qore) or service.QorusService (Java) directly. This means that Qore code can call the static methods defined in the base class directly.

For library classes and other service code, calls must be prefixed with the class name (also for all Java code as well).

Service Program Container

Each Qorus service has a single Qore Program object containing all its code for service methods, as well as any library 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:

Directive Constant Description
%no-top-level Qore::PO_NO_TOP_LEVEL_STATEMENTS No code is allowed in the top-level statement (outside a function or class)
%no-thread-control Qore::PO_NO_THREAD_CONTROL Thread management functionality is unavailable
%no-process-control Qore::PO_NO_PROCESS_CONTROL Functionality that affects the entire process is unavailable
%require-our Qore::PO_REQUIRE_OUR All variables must be declared before use

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:

Define Availability Description
Qorus W, S, J Identifies code in Qorus
QorusHasAlerts W, S, J Marks the availability of the alert API (Qorus 3.0+)
QorusHasHttpUserIndex S Marks the availability of OMQ::AbstractServiceHttpHandler::setUserIndexInfo() (Qorus 3.0+)
QorusHasTableCache W, S, J Marks the availability of the table cache API (Qorus 3.1+)
QorusHasUserConnections W, S, J Marks the availability of the connection API (Qorus 3.0+)
QorusServer W, S, J Identifies code used in Qorus server interfaces
QorusService S Identifies code used in a service Program container
Note
All defines set in qorus.defines (common to workflows, services, and jobs) are also set in service Program containers

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

The following APIs are imported into service program logic containers (see also OMQ::UserApi::Service):

Qore Method Java Method Qore Function Domain Availability Description
UserApi::auditCheckEventString() UserApi.auditCheckEventString() audit_check_event_string() Audit W, S, J checks if the given audit event (given as a string) is enabled
UserApi::auditCheckEvent() UserApi.auditCheckEvent() audit_check_event() Audit W, S, J checks if the given audit event (given as an integer code) is enabled
UserApi::auditGetMask() UserApi.auditGetMask() audit_get_mask() Audit W, S, J returns the audit event mask
UserApi::auditUserEvent() UserApi.auditUserEvent() audit_user_event() Audit W, S, J creates a user audit event (with audit event code OMQ::AE_USER_EVENT) against the workflow, service, or job instance
UserApi::callNetworkApi() UserApi.callNetworkApi() call_network_api() Utility W, S, J calls a system RPC API with system permissions
UserApi::callNetworkApiArgs() UserApi.callNetworkApiArgs() call_network_api_args() Utility W, S, J calls a system RPC API with system permissions with an explicit argument list argument
UserApi::callNetworkApiArgsWithAuthentication() UserApi.callNetworkApiArgsWithAuthentication() call_network_api_args_with_authentication() Utility W, S, J calls a system RPC API with authentication information (username and password)
UserApi::callRestApi() UserApi.callRestApi() call_rest_api() Utility W, S, J calls a system REST API with system permissions
UserApi::callRestApiWithAuthentication() UserApi.callRestApiWithAuthentication() call_rest_api_with_authentication() Utility W, S, J calls a system REST API with authentication information (username and password)
UserApi::clearSqlTableCache() UserApi.clearSqlTableCache() clear_sql_table_cache() SQL Cache W, S, J clears a cached table from the SQL cache
UserApi::createOrder() UserApi.createOrder() create_order() Utility W, S, J creates a workflow order data instance in the database and returns the workflow_instanceid of the order created
UserApi::createRemoteOrder() UserApi.createRemoteOrder() create_remote_order() Utility W, S, J creates a workflow order data instance in a remote Qorus instance and returns the workflow_instanceid of the order created
UserApi::deserializeQorusData() UserApi.deserializeQorusData() deserialize_qorus_data() Utility W, S, J deserializes strings to Qore data structures
UserApi::execSynchronousWorkflow() UserApi.execSynchronousWorkflow() exec_synchronous_workflow() Utility W, S, J executes a workflow order synchronously and returns the result of execution
UserApi::flushSlaEvents() UserApi.flushSlaEvents() flush_sla_events() SLA W, S, J flushes all pending SLA events to the DB
UserApi::getActiveJobs() UserApi.getActiveJobs() get_active_jobs() System Info W, S, J returns information about active jobs
ServiceApi::getConfigItemHash() ServiceApi.getConfigItemHash() n/a n/a S retrieves a hash of all service configuration items
ServiceApi::getConfigItemValue() ServiceApi.getConfigItemValue() n/a n/a S retrieves the value of a service configuration item
UserApi::getDatasourceDedicated() n/a get_datasource_dedicated() Connections W, S, J returns a dedicated Qore::SQL::Datasource object
UserApi::getDatasourcePool() UserApi.getDatasourcePool() get_datasource_pool() Connections W, S, J returns a shared Qore::SQL::DatasourcePool object
UserApi::getGlobalConfigItemValue() UserApi.getGlobalConfigItemValue() n/a Qorus System Information API W, S, J returns the value of the global configuration item on global level
ServiceApi::getOption() ServiceApi.getOption() get_option() Options W, S, J returns the value of one or more system or interface options
UserApi::getQorusOptions() UserApi.getQorusOptions() get_qorus_options() Options W, S, J returns the value of system options
UserApi::getQorusOptionsArgs() UserApi.getQorusOptionsArgs() get_qorus_options_args() Options W, S, J returns the value of system options
UserApi::getQorusOptionInfo() UserApi.getQorusOptionInfo() get_qorus_option_info() Options W, S, J returns information about system options
UserApi::getQorusOptionInfoArgs() UserApi.getQorusOptionInfoArgs() get_qorus_option_info_args() Options W, S, J returns information about system options
UserApi::getRemoteRestConnection() UserApi.getRemoteRestConnection() get_remote_rest_connection() Connections W, S, J returns a QorusSystemRestHelper to a remote Qorus instance
UserApi::getRemoteRpcConnection() n/a get_remote_rpc_connection() Connections W, S, J returns a QorusSystemAPIHelper to a remote Qorus instance
UserApi::getRunningWorkflowInfo() UserApi.getRunningWorkflowInfo() get_running_workflow_info() System Info W, S, J returns information about a running workflow execution instance
UserApi::getRunningWorkflowList() UserApi.getRunningWorkflowList() get_running_workflow_list() System Info W, S, J returns information about running workflow execution instances
UserApi::getServiceInfo() UserApi.getServiceInfo() get_service_info() System Info W, S, J returns information about a service
UserApi::getSessionId() UserApi.getSessionId() get_session_id() System Info W, S, J returns the current application session ID
UserApi::getSqlTable() UserApi.getSqlTable() get_sql_table() SQL Cache W, S, J retrieves an AbstractTable object from the SQL cache for DML operations
UserApi::getSqlCacheInfo() UserApi.getSqlCacheInfo() get_sql_cache_info() SQL Cache W, S, J returns information about the SQL cache
UserApi::getSystemInfo() UserApi.getSystemInfo() get_system_info() System Info W, S, J returns information about the system
UserApi::getSystemServiceInfo() UserApi.getSystemServiceInfo() get_system_service_info() System Info W, S, J returns information about a system service
UserApi::getUserConnection() UserApi.getUserConnection() get_user_connection() Connections W, S, J returns the given user connection object
UserApi::getUserServiceInfo() UserApi.getUserServiceInfo() get_user_service_info() System Info W, S, J returns information about a user service
UserApi::getValueMap() UserApi.getValueMap() get_value_map() Value Maps W, S, J retrieves a value mapping from a value map
UserApi::getValueMaps() UserApi.getValueMaps() get_value_maps() Value Maps W, S, J retrieves a list of all known value sets
UserApi::log() UserApi.log() log() logging W, S, J outputs a log message in the workflow's log file
UserApi::getNextSequenceValue() UserApi.getNextSequenceValue() next_sequence_value() Utility W, S, J returns the next value from the given datasource and database sequence
UserApi::postSlaEventError() UserApi.postSlaEventError() post_sla_event_error() SLA W, S, J posts an unsuccessful event for SLA and performance tracking
UserApi::postSlaEventSuccess() UserApi.postSlaEventSuccess() post_sla_event_success() SLA W, S, J posts a successful event for SLA and performance tracking
UserApi::postSyncEvent() UserApi.postSyncEvent() post_sync_event() Utility W, S, J posts a workflow synchronization event given the event type name and event key
UserApi::postUserEvent() UserApi.postUserEvent() post_user_event() Utility W, S, J posts an application event of class OMQ::QE_CLASS_USER
UserApi::propGet() UserApi.propGet() prop_get() System Props W, S, J returns the value of the given system property key in the given domain or NOTHING if the system property does not exist
UserApi::propUpdate() UserApi.propUpdate() prop_update() System Props W, S, J changes (inserts, updates, or deletes) the value of one or more system properties
UserApi::qorusGetLocalUrl() UserApi.qorusGetLocalUrl() qorus_get_local_url() System Info W, S, J returns a URL for the current system
UserApi::raiseTransientAlert() UserApi.raiseTransientAlert() raise_transient_alert() Alerts W, S, J raises a transient alert
UserApi::restartTransaction() UserApi.restartTransaction() restart_transaction() Utility W, S, J enables recovery from restartable DB communication errors
UserApi::runtimeProperties() UserApi.runtimeProperties() runtime_properties() System Info W, S, J returns information about runtime system defines defined
UserApi::serializeQorusData() UserApi.serializeQorusData() serialize_qorus_data() Utility W, S, J serializes Qore data structures to strings
ServiceApi::setOption() ServiceApi.setOption() set_option() Options W, S, J sets option values on a workflow, service, or job
ServiceApi::bindFtp() n/a svc_bind_ftp() Service FTP S Binds an FTP handler to the service and starts FTP listeners
ServiceApi::bindHandler() n/a svc_bind_handler() Service HTTP S Binds a new HTTP handler to a dedicated HTTP service listener
ServiceApi::bindHttp() n/a svc_bind_http() Service HTTP S Binds an HTTP handler to the service
ServiceApi::callApiAsCurrentUser() ServiceApi.callApiAsCurrentUser() svc_call_api_as_current_user() Service System S Calls a system RPC API as the current external user (if any) and returns the result
ServiceApi::checkAuthorization() ServiceApi.checkAuthorization() svc_check_authorization() Service RBAC S checks the current user for all given permissions and throws an exception if not
ServiceApi::checkAuthorizationOr() ServiceApi.checkAuthorizationOr() svc_check_authorization_or() Service RBAC S checks the current user for any of the given permissions and throws an exception if not
ServiceApi::checkJobAccess() ServiceApi.checkJobAccess() svc_check_job_access() Service RBAC S Checks if the current user can access all the given jobs and throws an exception if not
ServiceApi::checkJobInstanceAccess() ServiceApi.checkJobInstanceAccess() svc_check_job_instance_access() Service RBAC S Checks if the current user can access the given job instance and throws an exception if not
ServiceApi::checkMapperAccess() ServiceApi.checkMapperAccess() svc_check_mapper_access() Service RBAC S Checks if the current user can access all the given mappers and throws an exception if not
ServiceApi::checkQueueAccess() ServiceApi.checkQueueAccess() svc_check_queue_access() Service RBAC S Checks if the current user can access all the given asynchronous queues and throws an exception if not
ServiceApi::checkServiceAccess() ServiceApi.checkServiceAccess() svc_check_service_access() Service RBAC S Checks if the current user can access all the given services and throws an exception if not
ServiceApi::checkVmapAccess() ServiceApi.checkVmapAccess() svc_check_vmap_access() Service RBAC S Checks if the current user can access all the given value maps and throws an exception if not
ServiceApi::checkWorkflowAccess() ServiceApi.checkWorkflowAccess() svc_check_workflow_access() Service RBAC S Checks if the current user can access all the given workflows and throws an exception if not
ServiceApi::checkWorkflowInstanceAccess() ServiceApi.checkWorkflowInstanceAccess() svc_check_workflow_instance_access() Service RBAC S Checks if the current user can access the given workflow order instance and throws an exception if not
ServiceApi::getActiveJobsAsCurrentUser() ServiceApi.getActiveJobsAsCurrentUser() svc_get_active_jobs_as_current_user() Service Info S Returns a hash of all active jobs visible to the current external user (if any)
ServiceApi::getCallContext() ServiceApi.getCallContext() svc_get_call_context() Service Info S Returns a hash of contextual information about the current service call
ServiceApi::getCallContextString() ServiceApi.getCallContextString() svc_get_call_context_string() Service Info S Returns a string describing the context of the current call
ServiceApi::getHttpCallContext() ServiceApi.getHttpCallContext() svc_get_http_call_context() Service HTTP S Returns a hash with info about the external HTTP call, if any
ServiceApi::getJobAccessHash() ServiceApi.getJobAccessHash() svc_get_job_access_hash() Service RBAC S Returns a hash of all job IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no jobs
ServiceApi::getJobAccessList() ServiceApi.getJobAccessList() svc_get_job_access_list() Service RBAC S Returns a list of all job IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no jobs
ServiceApi::getLastEvents() ServiceApi.getLastEvents() svc_get_last_events() Service Events S Returns the last system events corresponding to the arguments
ServiceApi::getLastEventsAnd() ServiceApi.getLastEventsAnd() svc_get_last_events_and() Service Events S Returns the last system events that meet all the criteria given
ServiceApi::getLastEventsOr() ServiceApi.getLastEventsOr() svc_get_last_events_or() Service Events S Returns the last system events that meet any of the criteria given
ServiceApi::getMapperAccessHash() ServiceApi.getMapperAccessHash() svc_get_mapper_access_hash() Service RBAC S Returns a hash of all mapper IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no mappers
ServiceApi::getMapperAccessList() ServiceApi.getMapperAccessList() svc_get_mapper_access_list() Service RBAC S Returns a list of all mapper IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no mappers
ServiceApi::getResource() ServiceApi.getResource() svc_get_resource() Service Resources S returns the requested resource as a hash with HTTP headers and an HTTP response code to be used as the response for an HTTP request handler
ServiceApi::getResourceData() ServiceApi.getResourceData() svc_get_resource_data() Service Resources S returns the requested resource as its native type
ServiceApi::getResourceHash() ServiceApi.getResourceHash() svc_get_resource_hash() Service Resources S returns a hash describing all resources for the service
ServiceApi::getResourceList() ServiceApi.getResourceList() svc_get_resource_list() Service Resources S returns a list of all resources for the service
ServiceApi::getResourceWsdl() n/a svc_get_resource_wsdl() Service Resources S returns the given resource as a WebService object
ServiceApi::getRunningWorkflowListAsCurrentUser() ServiceApi.getRunningWorkflowListAsCurrentUser() svc_get_running_workflow_list_as_current_user() Service Info S Returns a list of running workflows visible to the current external user, if any
ServiceApi::getServiceAccessHash() ServiceApi.getServiceAccessHash() svc_get_service_access_hash() Service RBAC S Returns a hash of all services IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no services
ServiceApi::getServiceAccessList() ServiceApi.getServiceAccessList() svc_get_service_access_list() Service RBAC S Returns a list of all services IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no services
ServiceApi::getServiceInfo() ServiceApi.getServiceInfo() svc_get_service_info() Service Info S Returns a hash of information about the current service
ServiceApi::getServiceInfoAsCurrentUser() ServiceApi.getServiceInfoAsCurrentUser() svc_get_service_info_as_current_user() Service Info S Returns information about the given service if the current external user, if any, can access it
ServiceApi::getTemplateHash() ServiceApi.getTemplateHash() svc_get_template_hash() Service Resources S returns a hash describing all template resources for the service
ServiceApi::getTemplateList() ServiceApi.getTemplateList() svc_get_template_list() Service Resources S returns a list of all template resources for the service
ServiceApi::getVmapAccessHash() ServiceApi.getVmapAccessHash() svc_get_vmap_access_hash() Service RBAC S Returns a hash of all value map IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no value maps
ServiceApi::getVmapAccessList() ServiceApi.getVmapAccessList() svc_get_vmap_access_list() Service RBAC S Returns a list of all value map IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no value maps
ServiceApi::getWorkflowAccessHash() ServiceApi.getWorkflowAccessHash() svc_get_workflow_access_hash() Service RBAC S Returns a hash of all workflow IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no workflows
ServiceApi::getWorkflowAccessList() ServiceApi.getWorkflowAccessList() svc_get_workflow_access_list() Service RBAC S Returns a list of all workflow IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no workflows
ServiceApi::hasResource() ServiceApi.hasResource() svc_has_resource() Service Resources S returns True if the given resource exists
ServiceApi::hasTemplate() ServiceApi.hasTemplate() svc_has_template() Service Resources S returns True if the given resource is a template
ServiceApi::registerSoapHandler() n/a svc_register_soap_handler() Service SOAP S Registers the current service as a SOAP server
ServiceApi::renderTemplate() ServiceApi.renderTemplate() svc_render_template() Service Resources S explcitly renders the given template resource and returns the rendered data
ServiceApi::startThread() n/a svc_start_thread() Service Threads S Starts a service thread
ServiceApi::startThreadArgs() n/a svc_start_thread_args() Service Threads S Starts a service thread with the given arguments as a list argument
ServiceApi::testAuthorization() ServiceApi.testAuthorization() svc_test_authorization() Service RBAC S Returns True if the current user has all given permissions
ServiceApi::testAuthorizationOr() ServiceApi.testAuthorizationOr() svc_test_authorization_or() Service RBAC S Returns True if the current user has any of the given permissions
ServiceApi::testJobAccess() ServiceApi.testJobAccess() svc_test_job_access() Service RBAC S Returns True if the current user can access all the given jobs
ServiceApi::testMapperAccess() ServiceApi.testMapperAccess() svc_test_mapper_access() Service RBAC S Returns True if the current user can access all the given mappers
ServiceApi::testServiceAccess() ServiceApi.testServiceAccess() svc_test_service_access() Service RBAC S Returns True if the current user can access all the given services
ServiceApi::testVmapAccess() ServiceApi.testVmapAccess() svc_test_vmap_access() Service RBAC S Returns True if the current user can access all the given value maps
ServiceApi::testWorkflowAccess() ServiceApi.testWorkflowAccess() svc_test_workflow_access() Service RBAC S Returns True if the current user can access all the given workflows
ServiceApi::tryRenderTemplate() ServiceApi.tryRenderTemplate() svc_try_render_template() Service Resources S if the given template resource exists then it is rendered and the rendered data is returned
ServiceApi::tryGetResource() ServiceApi.tryGetResource() svc_try_get_resource() Service Resources S returns the given resource if it exists as a hash with HTTP headers and an HTTP response code to be used as the response for an HTTP request handler
ServiceApi::tryGetResourceData() ServiceApi.tryGetResourceData() svc_try_get_resource_data() Service Resources S returns the given resource if it exists as its native type
ServiceApi::uiExtensionRegister() n/a svc_ui_extension_register() Service HTTP S Registers the current service as a UI extension handler
ServiceApi::waitForEvents() ServiceApi.waitForEvents() svc_wait_for_events() Service Events S Waits for system events corresponding to the arguments
ServiceApi::waitForEventsAnd() ServiceApi.waitForEventsAnd() svc_wait_for_events_and() Service Events S Waits for system events that meet all the criteria given
ServiceApi::waitForEventsOr() ServiceApi.waitForEventsOr() svc_wait_for_events_or() Service Events S Waits for system events that meet any of the criteria given

Service API Classes

The following classes are imported into service program logic containers:

Qore Class Java Class Availability Description
AbstractAuthenticator n/a S Allows the service to define custom authentication handlers for external HTTP and FTP requests
AbstractFsRemoteReceive AbstractFsRemoteReceive W, S, J provides an API for streaming data from a remote filesystem through a remote Qorus instance
AbstractFtpHandler n/a S Allows the service to implement an FTP server and handle FTP requests from clients
AbstractHttpRequestHandler n/a S Allows the service to refer to AbstractHttpRequestHandler methods directly
AbstractParallelStream n/a W, S, J provides an abstract base class for streaming data to or from a remote database through a remote Qorus instance and also provides static helper methods
AbstractPersistentDataHelper n/a S Used when defining persistent HTTP connection support in services
AbstractRestClass n/a S Used when defining REST request handling in a service
AbstractRestStreamRequestHandler n/a S Allows the service to implement data stream handlers
AbstractServiceStream n/a S Used when defining custom stream handlers in a service
AbstractServiceDataStreamResponseHandler n/a S Used when defining custom stream handlers in a service
AbstractServiceHttpHandler n/a S Allows the Qorus HTTP server to redirect HTTP requests to a service
AbstractServiceRestHandler n/a S Allows the service to implement a REST handler and serve external REST requests
AbstractServiceWebSocketHandler n/a S Allows the service to implement a Web Socket service handler
DbRemote DbRemote W, S, J provides an API wrapper for all system.sqlutil service methods
DbRemoteReceive DbRemoteReceive W, S, J provides an API for streaming data from a remote database through a remote Qorus instance
DbRemoteSend DbRemoteSend W, S, J provides an API for streaming data to a remote database through a remote Qorus instance
DefaultQorusRBACAuthenticator n/a S the standard Qorus RBAC authentication class
DefaultQorusRBACBasicAuthenticator n/a S the standard Qorus RBAC authentication class that requests basic authentication with 401 Unauthorized responses
FsRemote FsRemote W, S, J provides an API wrapper for all system.fs service methods
FsRemoteSend FsRemoteSend W, S, J provides an API for streaming data to a remote filesystem through a remote Qorus instance
PermissiveAuthenticator n/a S Used to indiscriminately authenticate all requests in HTTP and FTP request handlers
QorusExtensionHandler n/a S Allows the service to extend the Qorus web UI
QorusInboundTableMapper InboundTableMapper W, S, J provides an API for mapping data to a DB table
QorusInboundTableMapperIterator n/a W, S, J provides an iterator-based API for mapping data to a DB table
QorusRawSqlStatementOutboundMapper RawSqlStatementOutboundMapper W, S, J provides an API for mapping from SQL statement using direct SQL statements passed in
QorusRemoteServiceHelper n/a W, S, J provides an API for calling service methods in remote Qorus instances
QorusSqlStatementOutboundMapper SqlStatementOutboundMapper W, S, J provides an API for mapping from SQL statement using SqlUtil
QorusSystemAPIHelper n/a W, S, J provides an API for calling RPC API methods in remote Qorus instances
OMQ::QorusSystemRestHelper QorusSystemRestHelper W, S, J provides an API for using the REST API in remote Qorus instances
QorusWebSocketConnection n/a S Used when defining web socket service handlers
RestHandler n/a S Allows the service to access RestHandler methods directly when servicing REST requests
ServiceApi ServiceApi S the primary service Qorus API class
ServiceFileHandler n/a S Allows services to implement HTTP file-based request handlers
UserApi UserApi W, S, J the primary shared Qorus API class

Service API Modules

The following modules are imported by default into service program logic containers:

Name Availability Description
json W, S, J provides APIs for JSON data serialization and deserialization support
Mime W, S, J provides MIME definitions and functionality
Mapper W, S, J provides a data-mapping API
SoapClient W, S, J provides a SOAP client API
SqlUtil W, S, J provides high-level APIs for programmatic DML (SQL data manipulation), DDL (creating, querying, manipulating database definitions), and DBA operations
TableMapper W, S, J provides high-level APIs for mapping data to and from database tables
Util W, S, J provides utility APIs
uuid W, S, J provides an API for generating UUIDs
xml W, S, J provides APIs for parsing, validating, and generating XML documents
yaml W, S, J provides APIs for Qore's YAML-based data serialization and deserialization support
Note
other modules can be imported using the %requires directive, and it's always safe to %require a module that's already imported into the current Program container

Service API Overview

This section lists all of the API methods specific to services; the main service API classes are:

Note
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.

Service logging APIs:

Service Resource APIs

Qore Method Java Method Qore Function Desc
ServiceApi::getResource() ServiceApi.getResource() svc_get_resource() returns the requested resource as a hash with HTTP headers and an HTTP response code to be used as the response for an HTTP request handler
ServiceApi::getResourceData() ServiceApi.getResourceData() svc_get_resource_data() returns the requested resource as its native type
ServiceApi::getResourceHash() ServiceApi.getResourceHash() svc_get_resource_hash() returns a hash describing all resources for the service
ServiceApi::getResourceList() ServiceApi.getResourceList() svc_get_resource_list() returns a list of all resources for the service
ServiceApi::getResourceWsdl() n/a svc_get_resource_wsdl() returns the given resource as a WebService object
ServiceApi::getTemplateHash() ServiceApi.getTemplateHash() svc_get_template_hash() returns a hash describing all template resources for the service
ServiceApi::getTemplateList() ServiceApi.getTemplateList() svc_get_template_list() returns a list of all template resources for the service
ServiceApi::hasResource() ServiceApi.hasResource() svc_has_resource() returns True if the given resource exists
ServiceApi::hasTemplate() ServiceApi.hasTemplate() svc_has_template() returns True if the given resource is a template
ServiceApi::renderTemplate() ServiceApi.renderTemplate() svc_render_template() explcitly renders the given template resource and returns the rendered data
ServiceApi::tryRenderTemplate() ServiceApi.tryRenderTemplate() svc_try_render_template() if the given template resource exists then it is rendered and the rendered data is returned
ServiceApi::tryGetResource() ServiceApi.tryGetResource() svc_try_get_resource() returns the given resource if it exists as a hash with HTTP headers and an HTTP response code to be used as the response for an HTTP request handler
ServiceApi::tryGetResourceData() ServiceApi.tryGetResourceData() svc_try_get_resource_data() returns the given resource if it exists as its native type

Service RBAC Functions

Qore Method Java Method Qore Function Desc
ServiceApi::checkAuthorization() ServiceApi.checkAuthorization() svc_check_authorization() checks the current user for all given permissions and throws an exception if not
ServiceApi::checkAuthorizationOr() ServiceApi.checkAuthorizationOr() svc_check_authorization_or() checks the current user for any of the given permissions and throws an exception if not
ServiceApi::checkJobAccess() ServiceApi.checkJobAccess() svc_check_job_access() Checks if the current user can access all the given jobs and throws an exception if not
ServiceApi::checkJobInstanceAccess() ServiceApi.checkJobInstanceAccess() svc_check_job_instance_access() Checks if the current user can access the given job instance and throws an exception if not
ServiceApi::checkMapperAccess() ServiceApi.checkMapperAccess() svc_check_mapper_access() Checks if the current user can access all the given mappers and throws an exception if not
ServiceApi::checkQueueAccess() ServiceApi.checkQueueAccess() svc_check_queue_access() Checks if the current user can access all the given asynchronous queues and throws an exception if not
ServiceApi::checkServiceAccess() ServiceApi.checkServiceAccess() svc_check_service_access() Checks if the current user can access all the given services and throws an exception if not
ServiceApi::checkVmapAccess() ServiceApi.checkVmapAccess() svc_check_vmap_access() Checks if the current user can access all the given value maps and throws an exception if not
ServiceApi::checkWorkflowAccess() ServiceApi.checkWorkflowAccess() svc_check_workflow_access() Checks if the current user can access all the given workflows and throws an exception if not
ServiceApi::checkWorkflowInstanceAccess() ServiceApi.checkWorkflowInstanceAccess() svc_check_workflow_instance_access() Checks if the current user can access the given workflow order instance and throws an exception if not
ServiceApi::getJobAccessHash() ServiceApi.getJobAccessHash() svc_get_job_access_hash() Returns a hash of all job IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no jobs
ServiceApi::getJobAccessList() ServiceApi.getJobAccessList() svc_get_job_access_list() Returns a list of all job IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no jobs
ServiceApi::getMapperAccessHash() ServiceApi.getMapperAccessHash() svc_get_mapper_access_hash() Returns a hash of all mapper IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no mappers
ServiceApi::getMapperAccessList() ServiceApi.getMapperAccessList() svc_get_mapper_access_list() Returns a list of all mapper IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no mappers
ServiceApi::getServiceAccessHash() ServiceApi.getServiceAccessHash() svc_get_service_access_hash() Returns a hash of all services IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no services
ServiceApi::getServiceAccessList() ServiceApi.getServiceAccessList() svc_get_service_access_list() Returns a list of all services IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no services
ServiceApi::getVmapAccessHash() ServiceApi.getVmapAccessHash() svc_get_vmap_access_hash() Returns a hash of all value map IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no value maps
ServiceApi::getVmapAccessList() ServiceApi.getVmapAccessList() svc_get_vmap_access_list() Returns a list of all value map IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no value maps
ServiceApi::getWorkflowAccessHash() ServiceApi.getWorkflowAccessHash() svc_get_workflow_access_hash() Returns a hash of all workflow IDs accessible by the user, NOTHING if there are no restrictions, or an empty hash if the user can access no workflows
ServiceApi::getWorkflowAccessList() ServiceApi.getWorkflowAccessList() svc_get_workflow_access_list() Returns a list of all workflow IDs accessible by the user, NOTHING if there are no restrictions, or an empty list if the user can access no workflows
ServiceApi::testAuthorization() ServiceApi.testAuthorization() svc_test_authorization() Returns True if the current user has all given permissions
ServiceApi::testAuthorizationOr() ServiceApi.testAuthorizationOr() svc_test_authorization_or() Returns True if the current user has any of the given permissions
ServiceApi::testJobAccess() ServiceApi.testJobAccess() svc_test_job_access() Returns True if the current user can access all the given jobs
ServiceApi::testMapperAccess() ServiceApi.testMapperAccess() svc_test_mapper_access() Returns True if the current user can access all the given mappers
ServiceApi::testServiceAccess() ServiceApi.testServiceAccess() svc_test_service_access() Returns True if the current user can access all the given services
ServiceApi::testVmapAccess() ServiceApi.testVmapAccess() svc_test_vmap_access() Returns True if the current user can access all the given value maps
ServiceApi::testWorkflowAccess() ServiceApi.testWorkflowAccess() svc_test_workflow_access() Returns True if the current user can access all the given workflows

Service SOAP Functions

Qore Class Java Class Availability Description
ServiceApi::registerSoapHandler() n/a svc_register_soap_handler() Registers the current service as a SOAP server

Service HTTP and UI Functions

Qore Class Java Class Availability Description
ServiceApi::bindHandler() n/a svc_bind_handler() Binds a new HTTP handler to a dedicated HTTP service listener
ServiceApi::bindHttp() n/a svc_bind_http() Binds an HTTP handler to the service
ServiceApi::uiExtensionRegister() n/a svc_ui_extension_register() Registers the current service as a UI extension handler
ServiceApi::getHttpCallContext() ServiceApi.getHttpCallContext() svc_get_http_call_context() Returns a hash with info about the external HTTP call, if any

Service FTP Functions

Qore Class Java Class Availability Description
ServiceApi::bindFtp() n/a svc_bind_ftp() Binds an FTP handler to the service and starts FTP listeners

Service Event Handling Functions

Qore Class Java Class Availability Description
ServiceApi::getLastEvents() ServiceApi.getLastEvents() svc_get_last_events() Returns the last system events corresponding to the arguments
ServiceApi::getLastEventsAnd() ServiceApi.getLastEventsAnd() svc_get_last_events_and() Returns the last system events that meet all the criteria given
ServiceApi::getLastEventsOr() ServiceApi.getLastEventsOr() svc_get_last_events_or() Returns the last system events that meet any of the criteria given
ServiceApi::waitForEvents() ServiceApi.waitForEvents() svc_wait_for_events() Waits for system events corresponding to the arguments
ServiceApi::waitForEventsAnd() ServiceApi.waitForEventsAnd() svc_wait_for_events_and() Waits for system events that meet all the criteria given
ServiceApi::waitForEventsOr() ServiceApi.waitForEventsOr() svc_wait_for_events_or() Waits for system events that meet any of the criteria given

Service System Functions

Qore Class Java Class Availability Description
ServiceApi::callApiAsCurrentUser() ServiceApi.callApiAsCurrentUser() svc_call_api_as_current_user() Calls a system RPC API as the current external user (if any) and returns the result

Service Info Functions

Qore Class Java Class Availability Description
ServiceApi::getActiveJobsAsCurrentUser() ServiceApi.getActiveJobsAsCurrentUser() svc_get_active_jobs_as_current_user() Returns a hash of all active jobs visible to the current external user (if any)
ServiceApi::getCallContext() ServiceApi.getCallContext() svc_get_call_context() Returns a hash of contextual information about the current service call
ServiceApi::getCallContextString() ServiceApi.getCallContextString() svc_get_call_context_string() Returns a string describing the context of the current call
ServiceApi::getRunningWorkflowListAsCurrentUser() ServiceApi.getRunningWorkflowListAsCurrentUser() svc_get_running_workflow_list_as_current_user() Returns a list of running workflows visible to the current external user, if any
ServiceApi::getServiceInfo() ServiceApi.getServiceInfo() svc_get_service_info() Returns a hash of information about the current service
ServiceApi::getServiceInfoAsCurrentUser() ServiceApi.getServiceInfoAsCurrentUser() svc_get_service_info_as_current_user() Returns information about the given service if the current external user, if any, can access it

Service Threading Functions

Qore Class Java Class Availability Description
ServiceApi::startThread() n/a svc_start_thread() Starts a service thread
ServiceApi::startThreadArgs() n/a svc_start_thread_args() Starts a service thread with the given arguments as a list argument

System 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

SYSTEM_STARTUP Event Information Description

Event constant: OMQ::QEC_SYSTEM_STARTUP

  • name: (string) the product string for Qorus Integrtion Engine
  • version: (string) the version string
  • build: (string) the build string

SYSTEM_HEALTH_CHANGED Event Information Description

Event constant: OMQ::QEC_SYSTEM_HEALTH_CHANGED

  • health: (string) one of "GREEN", "YELLOW", or "RED"
  • old-health: (string) the old health value before the change
  • ongoing: (int) the number of ongoing alerts
  • transient: (int) the number of transient alerts in the cache
  • cutoff: (absolute date) the date time of the cutoff for transient alerts

SYSTEM_REMOTE_HEALTH_CHANGED Event Information Description

Event constant: OMQ::QEC_SYSTEM_REMOTE_HEALTH_CHANGED

  • name: (string) the name of the remote Qorus connection
  • health: (string) one of "GREEN", "YELLOW", or "RED"
  • old-health: (string) the old health value before the change
  • url: (string) the URL to the remote system
  • error: (string) an error string

SYSTEM_ERROR Event Information Description

Event constant: OMQ::QEC_SYSTEM_ERROR

  • err: (string) the error code
  • desc: (string) the error description
  • info: (string) additional information about the error

SYSTEM_SHUTDOWN Event Information Description

Event constant: OMQ::QEC_SYSTEM_SHUTDOWN

Note
This event has no info hash.

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 or OMQ::WM_Recovery)
  • 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 or OMQ::WM_Recovery))
  • 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)

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

WORKFLOW_DATA_UPDATED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_UPDATED

  • 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)
  • datatype: Type of data updated: staticdata or dynamicdata

WORKFLOW_DATA_LOCKED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_LOCKED

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • workflow_instanceid: (int) The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
  • note: (string) the note stored against the workflow order when locking it

WORKFLOW_DATA_UNLOCKED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_DATA_UNLOCKED

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • workflow_instanceid: (int) The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
  • note: (string) the note stored against the workflow order when unlocking it

WORKFLOW_PERFORMANCE Event Information Description

Event constant: OMQ::QEC_WORKFLOW_PERFORMANCE

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • workflow_instanceid: (int) The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
  • status: (string) the workflow order's status
  • disposition: (string) a code giving the disposition of the workflow; see Workflow Order Complete Disposition Constants for possible values and their meanings
  • start: (date) the start timestamp for workflow order execution
  • end: (date) the end timestamp for the workflow order execution (i.e. when the final status is reached)
Note
These events are only emitted if system option qorus.workflow-perf-events is enabled and when workflow orders get a final status (final statuses are COMPLETE and CANCELED)

WORKFLOW_RECOVERED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_RECOVERED

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • old_statuses: (list<string>) a list of status values for orders that have been recovered and now have the status given by new_status
  • new_status: (string) a status value for recovered orders

WORKFLOW_STATS_UPDATED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_STATS_UPDATED

  • tag: the tag or label identifying the bands; either "global" for summarized global info or <id> where <id> is the workflow ID
  • bands: list of OrderSummaryOutputInfo hashes

WORKFLOW_STEP_DATA_UPDATED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_STEP_DATA_UPDATED

  • 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)
  • stepid: The stepid for the data that was updated
  • ind: the step instance index for the data that was updated
Since
Qorus 4.0.1

WORKFLOW_STEP_PERFORMANCE Event Information Description

Event constant: OMQ::QEC_WORKFLOW_STEP_PERFORMANCE

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • workflow_instanceid: (int) The workflow instance ID (i.e. workflow_instance.workflow_instanceid in the database)
  • stepname: (string) the name of the step
  • stepid: (int) the ID of the step
  • ind: (int) the array index for the step (always 0 for non-array steps)
  • start: (date) the start timestamp for workflow step execution
  • end: (date) the end timestamp for the workflow step execution
Note
These events are only emitted if system option qorus.workflow-step-perf-events is enabled

WORKFLOW_UPDATED Event Information Description

Event constant: OMQ::QEC_WORKFLOW_UPDATED

  • name: (string) The name of the workflow
  • version: (string) The version of the workflow
  • workflowid: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database)
  • [remote]: (bool) the new remote value
  • [autostart]: (int) the new autostart value
  • [sla_threshold]: (int) the new SLA threshold value

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

SERVICE_AUTOSTART_CHANGE Event Information Description

Event constant: OMQ::QEC_SERVICE_AUTOSTART_CHANGE

Deprecated:
This event it no longer raised as of Qorus 4.0

SERVICE_METHOD_PERFORMANCE Event Information Description

Event constant: OMQ::QEC_SERVICE_METHOD_PERFORMANCE

  • type: (string) the service type ("system" or "user")
  • name: (string) the name of the service
  • version: (string) the version of the service
  • serviceid: (int) the ID of the service
  • method: (string) the name of the service method called
  • start: (date) the start timestamp for the call
  • end: (date) the end timestamp for the call
  • error: (bool) an indicator if the call ended in an error or not
Note

SERVICE_UPDATED Event Information Description

Event constant: OMQ::QEC_SERVICE_UPDATED

  • type: (string) the service type ("system" or "user")
  • name: (string) the name of the service
  • version: (string) the version of the service
  • serviceid: (int) the ID of the service
  • [remote]: (bool) the new remote value
  • [autostart]: (bool) the new autostart value

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)

JOB_RECOVERED Event Information Description

Event constant: OMQ::QEC_JOB_RECOVERED

  • name: (string) The name of the job
  • version: (string) The version of the job
  • jobid: (int) The job ID (metadata ID, i.e. jobs.jobid in the database)
  • old_statuses: (list<string>) a list of status values for orders that have been recovered and now have the status given by new_status
  • new_status: (string) a status value for recovered job instances

JOB_UPDATED Event Information Description

Event constant: OMQ::QEC_JOB_UPDATED

  • name: (string) The name of the job
  • version: (string) The version of the job
  • jobid: (int) The job ID (metadata ID, i.e. jobs.jobid in the database)
  • [remote]: (bool) the new remote value
  • [sched_txt]: (string) the new schedule value
  • [month]: (string) the new month value
  • [day]: (string) the new day value
  • [wday]: (string) the new wday value
  • [hour]: (string) the new hour value
  • [minute]: (string) the new minute value
  • [active]: (bool) the new active value
  • [expiry_date]: (*date) the new expiry date or NOTHING if the expiry date has been cleared

CONFIG_ITEM_CHANGED Event Information Description

Event constant: OMQ::QEC_CONFIG_ITEM_CHANGED

  • interfaceType: (string) The type of the interface (job, service, step, workflow or global)
  • [type]: (string) The type of the service if the interface type is "service"
  • name: (string) The name of the interface
  • [version]: (string) The version of the interface if is present
  • [workflowid]: (int) The workflow ID (metadata ID, i.e. workflows.workflowid in the database) if the interface type is "workflow" or "step"
  • [stepid]: (int) The step ID (metadata ID, i.e. steps.stepid in the database) if the interface type is "step"
  • [serviceid]: (int) The service ID (metadata ID, i.e. services.serviceid in the database) if the interface type is "service"
  • [jobid:] (int) The job ID (metadata ID, i.e. jobs.jobid in the database) if the interface type is "job"
  • item: (string) the name of the configuration item
  • value: (any) the new value of the configuration item

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

CONNECTION_UP Event Information description

Event constant: OMQ::QEC_CONNECTION_UP

  • type: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type

CONNECTION_DOWN Event Information description

Event constant: OMQ::QEC_CONNECTION_DOWN

  • type: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type
  • err: (string) the error string

CONNECTION_ENABLED_CHANGE Event Information description

Event constant: OMQ::QEC_CONNECTION_ENABLED_CHANGE

  • type: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type
  • enabled: (bool) the enabled status for the connection

CONNECTION_CREATED Event Information description

Event constant: OMQ::QEC_CONNECTION_CREATED

  • conntype: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type
  • desc: (string) the description of the connection
  • url: (string) the URL for the connection
  • url_hash: (hash) a broken-down hash of url
  • opts: (hash) connection options
  • enabled: (bool) the enabled status of the connection
  • see the REST info response for the appopriate connection type for details about the message per connection type:

CONNECTION_UPDATED Event Information description

Event constant: OMQ::QEC_CONNECTION_UPDATED

  • conntype: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type
  • desc: (string) the description of the connection
  • url: (string) the URL for the connection
  • url_hash: (hash) a broken-down hash of url
  • opts: (hash) connection options
  • enabled: (bool) the enabled status of the connection
  • see the REST info response for the appopriate connection type for details about the message per connection type:

CONNECTION_DELETED Event Information description

Event constant: OMQ::QEC_CONNECTION_DELETED

  • type: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • name: (string) the unique name for the connection in its type

CONNECTIONS_RELOADED Event Information description

Event constant: OMQ::QEC_CONNECTIONS_RELOADED

  • type: (string) the connection type name (one of "DATASOURCE", "REMOTE", or "USER-CONNECTION")
  • connections: (list of hashes) list of connections reloaded

LOGGER_CREATED Event Information description

Event constant: OMQ::QEC_LOGGER_CREATED emitted when logger is created

  • loggerId: (string) logger id
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) interface id (not set for default loggers)
  • params: (hash) actual logger params
  • isDefault: (bool) true if created defaut logger

LOGGER_UPDATED Event Information description

Event constant: OMQ::QEC_LOGGER_UPDATED emitted when logger is updated

  • loggerId: (string) logger id
  • appenderIds: (list) list of assigned appender ids (not set if no appenders assigned)
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) interface id (not set for default loggers)
  • params: (hash) actual logger params
  • isDefault: (bool) true if edited defaut logger

LOGGER_DELETED Event Information description

Event constant: OMQ::QEC_LOGGER_DELETED emitted when logger is deleted

  • loggerId: (string) logger id
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) interface id (not set for default loggers)
  • current_logger: (hash) actual logger information
  • isDefault: (bool) true if deleted defaut logger

APPENDER_CREATED Event Information description

Event constant: OMQ::QEC_APPENDER_CREATED emitted when logger appender is created

  • loggerId: (string) logger id
  • logger_appenderid: (string) appender id
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) if exists contains interface name (e.g. workflow/jobs/services name)
  • params: (hash) actual appender params
  • isDefault: (bool) true if created appender for defaut logger

APPENDER_DELETED Event Information description

Event constant: OMQ::QEC_APPENDER_DELETED emitted when logger is created

  • logger_appenderid: (string) appender id
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) if exists contains interface name (e.g. workflow/jobs/services name)
  • isDefault: (bool) true if deleted appender from defaut logger

APPENDER_UPDATED Event Information description

Event constant: OMQ::QEC_APPENDER_UPDATED emitted when logger appender is updated

  • loggerId: (string) logger id
  • logger_appenderid: (string) appender id
  • interface: (string) type of related system (e.g. workflows, jobs, services, system, audit, http, ...)
  • interfaceId: (*string) if exists contains interface name (e.g. workflow/jobs/services name)
  • params: (hash) actual appender params
  • isDefault: (bool) true if created appender for defaut logger

PROCESS_STARTED Event Information description

Event constant: OMQ::QEC_PROCESS_STARTED

  • id: (string) the unique name for the process
  • node: (string) the node where the process is running
  • status: (int) the process status code; 0 = IDLE, 1 = STARTING, 2 = RUNNING, 3 = STOPPING, 4 = ERROR
  • urls: (list<string>) a list of distributed queue URLs for the proces
  • host: (string) the hostname of the node running the process
  • pid: (int) the PID of the process on the host
  • type: (string) the type of cluster process
  • client_id: (string) the type-specific ID for the process
  • start_code: (int) the start code or start reason: 0 = manual start, 1 = manual restart, 2 = automatic restart

PROCESS_START_ERROR Event Information Description

Event constant: OMQ::QEC_PROCESS_START_ERROR

  • id: (string) the unique name for the process
  • node: (string) the node where the process is running
  • status: (int) the process status code; 0 = IDLE, 1 = STARTING, 2 = RUNNING, 3 = STOPPING, 4 = ERROR
  • urls: (list<string>) a list of distributed queue URLs for the proces
  • host: (string) the hostname of the node running the process
  • pid: (int) the PID of the process on the host
  • type: (string) the type of cluster process
  • client_id: (string) the type-specific ID for the process
  • error: (string) the error string

PROCESS_STOPPED Event Information description

Event constant: OMQ::QEC_PROCESS_STOPPED

  • id: (string) the unique name for the process
  • node: (string) the node where the process is running
  • status: (int) the process status code; 0 = IDLE, 1 = STARTING, 2 = RUNNING, 3 = STOPPING, 4 = ERROR
  • urls: (list<string>) a list of distributed queue URLs for the proces
  • host: (string) the hostname of the node running the process
  • pid: (int) the PID of the process on the host
  • type: (string) the type of cluster process
  • client_id: (string) the type-specific ID for the process

PROCESS_MEMORY_CHANGED Event Information description

Event constant: OMQ::QEC_PROCESS_MEMORY_CHANGED

  • id: (string) the unique ID for the process
  • node: (string) the node where the process is running
  • status: (int) the process status code; 0 = IDLE, 1 = STARTING, 2 = RUNNING, 3 = STOPPING, 4 = ERROR
  • urls: (list<string>) a list of distributed queue URLs for the proces
  • host: (string) the hostname of the node running the process
  • pid: (int) the PID of the process on the host
  • type: (string) the type of cluster process
  • client_id: (string) the type-specific ID for the process
  • priv: (int) the amount of private memory (stacks, heap, non-shared, non-memory-mapped virtual memory segments) for the process in bytes
  • rss: (int) the resident size of the process in bytes
  • vsz: (int) the virtual memory size of the process in bytes (includes shared and memory-mapped segments)
  • pct: (int) the percentage of main memory on the node used by private memory
  • node_priv: (int) the amount of non-shared private memory used by the cluster on the node in bytes
  • node_priv_str: (string) a descriptive string giving the amount of non-shared private memory used by the cluster on the current node
  • node_ram: (int) the total amount of physical RAM on the node in bytes
  • node_ram_str: (string) a descriptive string giving the total amount of physical RAM on the node
  • node_ram_in_use: (int) the amount of physical RAM in use on the node in bytes
  • node_ram_in_use_str: (string) a descriptive string giving the amount of physical RAM in use on the node
  • node_cpu_count: (int) the number of CPUs on the node
  • node_load_pct: (float) the average load on the machine over the last minute

NODE_INFO Event Information Description

Event constant: OMQ::QEC_NODE_INFO

  • name: (string) the name of the node
  • node_priv: (int) the amount of private memory used by Qorus processes for the instance on the node
  • node_priv_str: (string) a string corresponding to node_priv
  • node_ram_in_use: (int) the amount of physical RAM in use on the node in bytes
  • node_ram_in_use_str: (string) a descriptive string giving the amount of physical RAM in use on the node
  • node_cpu_count: (int) the number of CPUs on the node
  • node_load_pct: (float) the average load on the machine over the last minute
  • processes: (int) the number of Qorus processes for the instance on the node

USER_EVENT Event Information Description

Event constant: OMQ::QEC_USER_EVENT

The info hash for user events is free form; any serializable information can be included in the info hash.

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-small.png
Qorus Integration Engine®