Qorus Integration Engine®  5.1.39_git
OMQ::UserApi::Service::ServiceApi Class Reference

primary service API class More...

Inheritance diagram for OMQ::UserApi::Service::ServiceApi:
OMQ::UserApi::UserApi

Static Public Member Methods

static checkAuthorization ()
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationArgs (softlist< string > args)
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationOr ()
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkAuthorizationOrArgs (softlist< string > args)
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static bool testAuthorization ()
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationArgs (softlist< string > args)
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationOr ()
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testAuthorizationOrArgs (softlist< string > args)
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static checkWorkflowAccess (list< auto > ids)
 checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized More...
 
static checkWorkflowAccess (softint id)
 checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized More...
 
static bool testWorkflowAccess (list< auto > ids)
 tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testWorkflowAccess (softint id)
 tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getWorkflowAccessList ()
 returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getWorkflowAccessHash ()
 returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkWorkflowInstanceAccess (softstring wfiid)
 checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized More...
 
static checkServiceAccess (list< auto > ids)
 checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized More...
 
static checkServiceAccess (softint id)
 checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized More...
 
static checkQueueAccess (softint queueid, string key)
 checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized More...
 
static bool testServiceAccess (list< auto > ids)
 tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testServiceAccess (softint id)
 tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getServiceAccessList ()
 returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static *hash< auto > getServiceAccessHash ()
 returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static checkJobAccess (list< auto > ids)
 checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized More...
 
static checkJobAccess (softint id)
 checks if the current user has access to the given single job ID; throws an exception if the user is not authorized More...
 
static bool testJobAccess (list< auto > ids)
 tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testJobAccess (softint id)
 tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getJobAccessList ()
 returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getJobAccessHash ()
 returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkJobInstanceAccess (softstring jiid)
 checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized More...
 
static checkMapperAccess (list< auto > ids)
 checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized More...
 
static checkMapperAccess (softint id)
 checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized More...
 
static bool testMapperAccess (list< auto > ids)
 tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testMapperAccess (softint id)
 tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getMapperAccessList ()
 returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getMapperAccessHash ()
 returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkVmapAccess (list< auto > ids)
 checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized More...
 
static checkVmapAccess (softint id)
 checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized More...
 
static bool testVmapAccess (list< auto > ids)
 tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testVmapAccess (softint id)
 tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getVmapAccessList ()
 returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getVmapAccessHash ()
 returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkFsmAccess (list< auto > ids)
 checks if the current user has access to the given list of Finite State Machines; throws an exception if the user is not authorized More...
 
static checkFsmAccess (string name)
 checks if the current user has access to the given single Finite State Machine; throws an exception if the user is not authorized More...
 
static bool testFsmAccess (list< auto > ids)
 tests if the current user has access to the given list of Finite State Machines and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testFsmAccess (string name)
 tests if the current user has access to the given single Finite State Machine and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getFsmAccessList ()
 returns a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getFsmAccessHash ()
 returns a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkPipelineAccess (list< auto > ids)
 checks if the current user has access to the given list of data pipelines; throws an exception if the user is not authorized More...
 
static checkPipelineAccess (string name)
 checks if the current user has access to the given single data pipeline; throws an exception if the user is not authorized More...
 
static bool testPipelineAccess (list< auto > ids)
 tests if the current user has access to the given list of data pipelines and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testPipelineAccess (string name)
 tests if the current user has access to the given single data pipeline and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getPipelineAccessList ()
 returns a list of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getPipelineAccessHash ()
 returns a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserAuthorization (string user)
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkUserAuthorizationArgs (string user, softlist< string > args)
 checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkUserAuthorizationOr (string user)
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static checkUserAuthorizationOrArgs (string user, softlist< string > args)
 checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized More...
 
static bool testUserAuthorization (string user)
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserAuthorizationArgs (string user, softlist< string > args)
 tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserAuthorizationOr (string user)
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserAuthorizationOrArgs (string user, softlist< string > args)
 tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static checkUserWorkflowAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized More...
 
static checkUserWorkflowAccess (string user, softint id)
 checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized More...
 
static bool testUserWorkflowAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserWorkflowAccess (string user, softint id)
 tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserWorkflowAccessList (string user)
 returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserWorkflowAccessHash (string user)
 returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserWorkflowInstanceAccess (string user, softstring wfiid)
 checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized More...
 
static checkUserServiceAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized More...
 
static checkUserServiceAccess (string user, softint id)
 checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized More...
 
static checkUserQueueAccess (string user, softint queueid, string key)
 checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized More...
 
static bool testUserServiceAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserServiceAccess (string user, softint id)
 tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserServiceAccessList (string user)
 returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static *hash< auto > getUserServiceAccessHash (string user)
 returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned More...
 
static checkUserJobAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized More...
 
static checkUserJobAccess (string user, softint id)
 checks if the current user has access to the given single job ID; throws an exception if the user is not authorized More...
 
static bool testUserJobAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserJobAccess (string user, softint id)
 tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserJobAccessList (string user)
 returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserJobAccessHash (string user)
 returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserJobInstanceAccess (string user, softstring jiid)
 checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized More...
 
static checkUserMapperAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized More...
 
static checkUserMapperAccess (string user, softint id)
 checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized More...
 
static bool testUserMapperAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserMapperAccess (string user, softint id)
 tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserMapperAccessList (string user)
 returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserMapperAccessHash (string user)
 returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserVmapAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized More...
 
static checkUserVmapAccess (string user, softint id)
 checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized More...
 
static bool testUserVmapAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserVmapAccess (string user, softint id)
 tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserVmapAccessList (string user)
 returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserVmapAccessHash (string user)
 returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserFsmAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of Finite State Machines; throws an exception if the user is not authorized More...
 
static checkUserFsmAccess (string user, string name)
 checks if the current user has access to the given single Finite State Machine; throws an exception if the user is not authorized More...
 
static bool testUserFsmAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of Finite State Machines and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserFsmAccess (string user, string name)
 tests if the current user has access to the given single Finite State Machine and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserFsmAccessList (string user)
 returns a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserFsmAccessHash (string user)
 returns a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static checkUserPipelineAccess (string user, list< auto > ids)
 checks if the current user has access to the given list of data pipelines; throws an exception if the user is not authorized More...
 
static checkUserPipelineAccess (string user, string name)
 checks if the current user has access to the given single data pipeline; throws an exception if the user is not authorized More...
 
static bool testUserPipelineAccess (string user, list< auto > ids)
 tests if the current user has access to the given list of data pipelines and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static bool testUserPipelineAccess (string user, string name)
 tests if the current user has access to the given single data pipeline and returns True (if authorization is granted) or False (if the user is not authorized) More...
 
static *list< auto > getUserPipelineAccessList (string user)
 returns a list of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static *hash< auto > getUserPipelineAccessHash (string user)
 returns a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned More...
 
static registerSoapHandler (hash< auto > h)
 registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol More...
 
static *hash< auto > getHttpCallContext ()
 returns a hash with HTTP call context information More...
 
static hash< auto > getLastEvents (softint count)
 returns the last system events More...
 
static hash< auto > getLastEventsOr (softint count, auto filter, auto and_not)
 gets the last system events that meet any of the filter criteria and none of the "and_not" criteria, if present More...
 
static hash< auto > getLastEventsAnd (softint count, auto filter, auto or_not)
 gets the last system events that meet all of the filter criteria or none of the "or_not" criteria, if present More...
 
static hash< auto > waitForEvents (softint min_id=1, timeout timeout_ms=0)
 return available system events More...
 
static hash< auto > waitForEventsOr (softint min_id=1, auto filter, timeout timeout_ms=0, auto and_not)
 return system events that meet any of the given criteria and none of the optional "and not" criteria More...
 
static hash< auto > waitForEventsAnd (softint min_id=1, auto filter, timeout timeout_ms=0, auto or_not)
 return system events that meet all of the given criteria or none of the optional "or not" criteria More...
 
static int startThread (auto code)
 starts a service thread; passes the remaining arguments to the function to the new thread More...
 
static int startThreadArgs (auto code, auto args)
 starts a service thread; uses the second argument as the argument list to pass to the new thread More...
 
static hash< auto > getServiceInfo (*hash< auto > cx)
 returns information about the current service More...
 
static bindFtp (OMQ::AbstractFtpHandler handler)
 binds an FTP handler to the service; listeners are started according to the listener information in the OMQ::AbstractFtpHandler argument More...
 
static list< stringbindHttp (OMQ::AbstractServiceHttpHandler handler, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 binds an HTTP handler to the service More...
 
static bindHandler (string name, OMQ::AbstractServiceHttpHandler handler)
 binds a new handler to a dedicated HTTP service listener by name More...
 
static bindHandler (string name, HttpServer::AbstractHttpRequestHandler handler, string url, *softlist< auto > content_type, *softlist< auto > special_headers, bool isregex=True)
 binds a new handler to a dedicated HTTP service listener by name More...
 
static *hash< auto > getCallContext ()
 returns contextual information about the current call More...
 
static string getCallContextString (*hash< auto > cx)
 returns a string describing the current call context More...
 
static auto callApiAsCurrentUser (string call, softlist< auto > args)
 calls a system API with the argument list to the API method as a top-level argument to this method as the current user More...
 
static *hash< auto > getServiceInfoAsCurrentUser (string type, string name, *hash< auto > cx)
 returns information about the given service from the service name (if it's currently loaded) and if the calling user can access the service More...
 
static *hash< auto > getServiceInfoAsCurrentUser (softint id, *hash< auto > cx)
 returns information about the given service from the serviceid (if it's currently loaded) and if the calling user can access the service More...
 
static list< hash< auto > > getRunningWorkflowListAsCurrentUser (string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances if the current user can access them More...
 
static hash< auto > getActiveJobsAsCurrentUser ()
 Returns information on all active jobs visible to the given user. More...
 
static hash< auto > getResource (string name, hash< auto > ctx, int code=200, *hash< auto > hdr)
 Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static *hash< auto > tryGetResource (string name, hash< auto > ctx, int code=200, *hash< auto > hdr)
 Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned. More...
 
static *hash< auto > getResourceHash ()
 returns a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none More...
 
static list< stringgetResourceList ()
 returns a list of the service's file resources or NOTHING if the service has none More...
 
static data getResourceData (string name, *hash< auto > ctx)
 Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static WSDL::WebService getResourceWsdl (string name, *hash< auto > ctx)
 Returns the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised. More...
 
static *data tryGetResourceData (string name, *hash< auto > ctx)
 Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned. More...
 
static bool hasResource (string name)
 returns True if the given service file resource exists, False if not More...
 
static hash< auto > renderTemplate (string name, hash< auto > ctx)
 explicitly renders a template file resource given the template argument hash More...
 
static *hash< auto > tryRenderTemplate (string name, hash< auto > ctx)
 render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING More...
 
static *hash< auto > getTemplateHash ()
 returns a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none More...
 
static list< stringgetTemplateList ()
 returns a list of the service's template file resources or NOTHING if the service has none More...
 
static bool hasTemplate (string name)
 returns True if the given service template file resource exists, False if not More...
 
static uiExtensionRegister (OMQ::QorusExtensionHandler handler)
 registers the service as an extension of the system UI More...
 
static uiExtensionRegister (OMQ::QorusExtensionHandler handler, string url_name)
 registers the service as an extension of the system UI with deterministic URL path More...
 
static streamRegister (string name, softlist< string > methods, code factory, string desc)
 registers an HTTP chunked data handler as a service resource More...
 
static persistenceRegister (code factory)
 registers the service as providing persistent/dedicated HTTP connection support More...
 
static persistenceThreadTerminate ()
 terminates a persistent connection in the current thread More...
 
static list< hash< auto > > startListeners (softstring bind, *string cert_path, *string key_path, *string key_password, *string name, int family=AF_UNSPEC)
 starts one or more new global HTTP listeners; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given More...
 
static stopListener (softstring name)
 stops a single listener based on its name or bind address; does not return until all connections on the listener have closed More...
 
static stopListenerId (softint id)
 stops a single listener based on its listener ID; does not return until all connections on the listener have closed More...
 
static list< stringregisterSoapListener (hash< auto > sh, softstring bind, int family=AF_UNSPEC, *HttpServer::AbstractAuthenticator auth, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 starts a dedicated SOAP listener with the given WSDL and registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol More...
 
static list< stringregisterSoapListeners (list< auto > sl, softstring bind, *hash< auto > lh, int family=AF_UNSPEC, *HttpServer::AbstractAuthenticator auth, hash< HttpBindOptionInfo > opts=< HttpBindOptionInfo >{})
 starts a dedicated SOAP listener with one or more WSDLs and registers the current service as a SOAP service and exports all methods that map to SOAP operations in the given WSDLs to be called from the Qorus HttpServer with the SOAP protocol More...
 
static *hash< auto > tryGetWfStaticData ()
 return the static data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING
 
static *hash< auto > tryGetWfDynamicData ()
 return the dynamic data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING
 
static *hash< auto > tryGetWfTempData ()
 return the temp data hash for the current workflow order if the service call was made from a workflow order, otherwise return NOTHING
 
static saveStateData (*hash< auto > data)
 serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA More...
 
static saveStateDataPath (string path, auto value)
 serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA More...
 
static *hash< auto > getStateData ()
 returns any service state state data stored with saveStateData() More...
 
static setOption (hash< auto > opts)
 Changes option values on a service. More...
 
static setOption (string option, auto value)
 Changes a single option value on a service. More...
 
static auto getOption ()
 Returns the value of the named service option(s) More...
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named service option or options. More...
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds More...
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static int usleep (date arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static auto getConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
 returns the value of the given service configuration item More...
 
static hash< auto > getConfigItemHash (*hash< auto > local_context)
 returns a hash of all configuration items for the current service More...
 
static setConfigItemChangeCallback (*code callback)
 Set a callback for config item value changes in the service. More...
 
static string generateTokenForCurrentUser (timeout expiry=DefaultTokenExpirationPeriod)
 Generates an access token for the current user with the given expiration time. More...
 
static string generateTokenForCurrentUser (int expiry_seconds)
 Generates an access token for the current user with the given expiration time. More...
 
static string generateTokenCheckUser (string username, int expire_seconds)
 Generates an authentication token for the given user. More...
 
static string generateTokenCheckUser (string username, timeout expiry)
 Generates an authentication token for the given user. More...
 
static string generateTokenLoginUser (string username, int expire_seconds, reference< hash< auto >> cx)
 Generates an authentication token for the given user and logs the user in for the existing connection context. More...
 
static string generateTokenLoginUser (string username, timeout expiry, reference< hash< auto >> cx)
 Generates an authentication token for the given user and logs the user in for the existing connection context. More...
 
static setUserLoginContextFromToken (string token, reference< hash< auto >> cx)
 Sets the user login context from the given token. More...
 
- Static Public Member Methods inherited from OMQ::UserApi::UserApi
static *hash< auto > getUserServiceInfo (string name)
 returns information about the given user service (if it's currently loaded) More...
 
static SqlUtil::AbstractTable getSqlTable (string datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static SqlUtil::AbstractTable getSqlTable (AbstractDatasource datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch More...
 
static hash< auto > getSqlCacheInfo ()
 get information about cached object More...
 
static clearSqlTableCache (string datasource, *string table_name)
 clears all objects for given datasource from the cache (for example, if database objects have been updated in the dataserver) More...
 
static clearSqlTableCache (AbstractDatasource datasource, *string table_name)
 clears cached objects for given datasource (for example, if database objects have been updated in the dataserver) More...
 
static auto getValueMap (string mapname, string key)
 Gets a lookup value from the value map by a key; the value map must be registered to the current interface. More...
 
static list< auto > getValueMaps ()
 Gets all value maps valid for the current interface. More...
 
static bool postSlaEventSuccess (string sla, number value)
 posts a successful SLA event for SLA monitoring and performance tracking More...
 
static bool postSlaEventError (string sla, number value, string err, string desc)
 posts an unsuccessful SLA event for SLA monitoring and performance tracking More...
 
static flushSlaEvents ()
 flushes all pending SLA events to disk and returns after the data has been committed More...
 
static *hash< auto > getSystemServiceInfo (string name)
 returns information about the given system service (if it's currently loaded) More...
 
static *hash< auto > getServiceInfo (string type, string name)
 returns information about the given service (if it's currently loaded) More...
 
static list getRunningWorkflowList (*string name, *string ver)
 returns a list of hashes giving information about the currently-running workflow execution instances More...
 
static hash getRunningWorkflowInfo (softint id)
 returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not More...
 
static softint createOrder (string name, *string version, hash< auto > params, string status=StatReady)
 creates a workflow order data instance in the database More...
 
static softint createRemoteOrder (string remote, string name, *string version, hash< auto > params, string status=StatReady, bool register_dependency=True)
 creates a workflow order data instance in a remote Qorus instance More...
 
static hash< auto > execSynchronousWorkflow (string name, *string version, hash< auto > sdata, *hash< auto > opts, *hash< auto > ddata, softint priority=DefaultOrderPriority, *hash< auto > orderkeys, *softstring external_order_instanceid, *softint parent_workflow_instanceid)
 executes a workflow order synchronously and returns the final status and order ID in a hash More...
 
static int postUserEvent (string severity, auto info)
 posts an application event of class QE_CLASS_USER More...
 
static hash runtimeProperties ()
 returns Qorus runtime properties as a hash More...
 
static auto callNetworkApiArgsWithAuthentication (string user, string pass, string call, softlist< auto > args)
 calls a system RPC API with authentication information (username and password) More...
 
static auto callNetworkApiArgs (string call, *softlist< auto > args)
 calls a system RPC API with the argument list to the API method as a top-level argument to this method; the API is called with system permissions (no restrictions) More...
 
static auto callNetworkApi (string call)
 calls a system RPC API and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApi (string method, string path, *hash< auto > body_args)
 calls a system REST API method and returns the result; the API is called with system permissions (no restrictions) More...
 
static auto callRestApiWithAuthentication (string user, string pass, string method, string path, *hash< auto > body_args)
 calls a system REST API method with authentication information (username and password) and returns the result More...
 
static hash< auto > getSystemInfo ()
 returns a hash of system info More...
 
static int getSessionId ()
 returns the current Qorus application session ID More...
 
static startCapturingObjectsFromJava ()
 Starts capturing Qore objects created from Java APIs in the current interface's object cache. More...
 
static stopCapturingObjectsFromJava ()
 Stops capturing Qore objects created from Java APIs in the current interface's object cache. More...
 
static startCapturingObjectsFromPython ()
 Starts capturing Qore objects created from Python APIs in the current interface's object cache. More...
 
static stopCapturingObjectsFromPython ()
 Stops capturing Qore objects created from Python APIs in the current interface's object cache. More...
 
static saveObjectInObjectCache (object obj)
 Saves the object in the object cache. More...
 
static bool clearObjectFromObjectCache (object obj)
 Removes the object from the object cache. More...
 
static *date checkObjectCache (object obj)
 Returns the date/time the object was cached or NOTHING if the object is not in the cache. More...
 
static int getObjectCacheSize ()
 Returns the number of objects in the cache. More...
 
static int clearObjectCache ()
 Clears the entire the object cache. More...
 
static int clearObjectCache (date cutoff)
 Clears the entire the object cache for all objects cached before the given date/time. More...
 
static list< hash< CallStackInfo > > getThreadCallStack ()
 Allows the current thread's call stack to be retrieved in Qorus. More...
 
static logFatal (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logError (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logWarn (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logInfo (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logDebug (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logTrace (softstring msg)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsFatal (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logWithLevel (int level, string msg)
 Writes to the current interface log file with the given log level. More...
 
static logWithLevelArgs (int level, string msg, *softlist< auto > args)
 Writes to the current interface log file with the given log level. More...
 
static logArgsError (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsWarn (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsInfo (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsDebug (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static logArgsTrace (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower. More...
 
static *int auditUserEvent (string user_event, *string info1, *string info2)
 creates a user audit event (with audit code AE_USER_EVENT) against the workflow, service, or job instance More...
 
static bool auditCheckEventString (string opt)
 checks if the given audit event (given as a string) is enabled More...
 
static bool auditCheckEvent (softint opt)
 checks if the given audit event (given as an integer code) is enabled More...
 
static int auditGetMask ()
 returns the audit event mask More...
 
static bool isKubernetes ()
 returns True when Qorus is running under Kubernetes More...
 
static int usleep (date arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static int sleep (softint arg)
 puts the current thread to sleep for a certain number of seconds More...
 
static int usleep (softint arg)
 puts the current thread to sleep for a certain number of microseconds More...
 
static hash< auto > getQorusOptions ()
 returns the value of the given system option or options More...
 
static hash< auto > getQorusOptionInfo ()
 returns a hash giving information about system options
 
static hash< auto > getQorusOptionInfoArgs (*list< auto > args)
 returns a hash giving information about system options
 
static auto getQorusOptionsArgs (softlist< auto > args)
 returns the value of the given system option or options
 
static hash< auto > getActiveJobs ()
 Returns information on all active jobs visible to the calling user. More...
 
static object getUserConnection (string name, bool connect=True, bool register_dependency=True, *hash< auto > rtopts)
 Returns an object corresponding to a defined user connection. More...
 
static hash< auto > getUserConnectionTags (string name)
 Returns any tags set on the given user connection. More...
 
static Qore::SQL::Datasource getDatasourceDedicated (string name, bool register_dependency=True)
 returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions More...
 
static AbstractDatasource getDatasourcePool (string name, bool register_dependency=True)
 returns a DatasourcePool object for the given datasource name More...
 
static hash< auto > getDatasourceInfo (string name)
 returns a hash of information for the given datasource, if known, otherwise throws an exception More...
 
static QorusSystemAPIHelper getRemoteRpcConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus remote connection. More...
 
static QorusSystemRestHelper getRemoteRestConnection (string name, bool connect=True, bool register_dependency=True)
 Returns a new QorusSystemRestHelper object corresponding to a defined Qorus remote connection. More...
 
static raiseTransientAlert (string alert, string reason, *hash< auto > info)
 raises a transient system alert from a workflow, service, or job More...
 
static string qorusGetLocalUrl (*string username, *string password)
 returns a string giving the local system URL More...
 
static setOption (hash< auto > hash)
 Changes option values on a workflow, service, or job. More...
 
static auto getOption ()
 Returns the value of the named workflow, service, or job option or options. More...
 
static auto getOptionArgs (*softlist< string > args)
 Returns the value of the named workflow, service, or job option or options. More...
 
static hash< auto > blockOrder (softint wfiid)
 block the given workflow order data instance More...
 
static hash< auto > unblockOrder (softint wfiid, *hash< auto > tempdata, *hash< auto > orderkeys)
 unblocks the given workflow order data instance More...
 
static hash< auto > cancelOrder (softint wfiid)
 cancel the given workflow order data instance More...
 
static hash< auto > uncancelOrder (softint wfiid, *hash< auto > tempdata)
 uncancels the given workflow order data instance More...
 
static updateDynamicOrderData (softint wfiid, hash< auto > new_data)
 updates the given workflow order instance's dynamic data hash atomically More...
 
static updateDynamicOrderDataPath (softint wfiid, string path, auto value)
 updates the given workflow order instance's dynamic data hash atomically More...
 
static *hash< auto > getUserContextInfo ()
 returns a hash for the current user context More...
 
static *string getContextUserName ()
 returns the current username for any external user-initiated call or NOTHING if executing in a system context More...
 
static auto getConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
 returns config item value in the current user context More...
 
static auto getInterfaceConfigItemValue (string cfg_item, *hash< auto > local_context, bool expand_complex_values=True)
 returns config item value in the current interface context More...
 
static hash< auto > getConfigItemHash (*hash< auto > local_context)
 returns a hash of all configuration items for the current interface More...
 
static hash< auto > getInterfaceConfigItemHash (*hash< auto > local_context)
 Returns a hash of all configuration items for the current context as a combination of local and global configuration items. More...
 
static auto getGlobalConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static auto getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context, bool expand_complex_values=True)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item More...
 
static AbstractDataProvider getDataProvider (string path)
 returns the data provider given by a path string More...
 
static AbstractDataProvider getDataProvider (string type, string name, *string path, *hash< auto > opts, *hash< auto > ctxt)
 returns the data provider given by a path string More...
 
static AbstractDataProviderType getQorusType (string type_path)
 Returns a data provider type from a direct type path. More...
 
static AbstractDataProviderType getTypeFromPath (string path)
 returns a data provider type identified by a path string More...
 
static Mapper::Mapper getMapper (string name, *hash< auto > rtopts)
 returns the given mapper if registered for the current interface More...
 
static Qore::AbstractIterator getMapperIterator (string name, Qore::AbstractIterator input, *hash< auto > rtopts)
 returns an iterator for the named mapper using the iterator argument for input More...
 
static bool postSyncEvent (string eventtype, string eventkey)
 posts a workflow synchronization event given the event type name and the unique event key More...
 
static hash< auto > propGet ()
 returns a hash of all system properties in all domains More...
 
static *hash< auto > propGet (string domain)
 returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist More...
 
static auto propGet (string domain, string key)
 returns the value of the given system property key in the given domain or NOTHING if the system property does not exist More...
 
static string propUpdate (string domain, softstring key, auto value)
 changes (inserts, updates, or deletes) the value of a single system property More...
 
static hash< auto > propUpdate (hash< auto > h)
 changes (inserts, updates, or deletes) the value of one or more system properties according to a hash argument More...
 
static softint getNextSequenceValue (AbstractDatasource ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static softint getNextSequenceValue (string ds, string name)
 returns the next sequence value for the given datasource and sequence More...
 
static string serializeQorusData (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static string serializeQorusDataWithNothing (auto d)
 returns a string giving the default serialization of the given data structure for storage in Qorus More...
 
static auto deserializeQorusData (string data)
 parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data More...
 
static auto deserializeQorusData (null data)
 deserializing a NULL value from the DB returns no value
 
static *string restartTransaction (string driver, hash< auto > ex)
 returns a string error message if any exception in the chain passed was caused by a recoverable DB error, otherwise returns NOTHING More...
 
static bool isInternalSystemDebuggingEnabled ()
 returns True if internal system debugging is enabled
 
static auto getHashDotValue (*hash< auto > var_data, string var_name, *reference< bool > missing_input)
 returns the value of the given key from the given hash, respects dot notation in the key name More...
 
static auto expandOneVariable (string str, string var_context, auto template_arg, *hash< auto > local_context, *bool brackets, bool expand_complex_values=True, *reference< bool > missing_input)
 expands one variable in a templated string More...
 
static bool isSingleTemplatedString (auto value)
 checks if the given value is a templated string with only one expandable variable More...
 
static auto expandTemplatedValue (auto value, *hash< auto > local_context, bool expand_complex_values=True, *reference< bool > missing_input, *string template_context)
 expands all variables in a templated string More...
 
static softlist< auto > expandComplexValue (list< auto > val, *hash< auto > local_context)
 expands all variables in a list with templated values More...
 
static hash< auto > expandComplexValue (hash< auto > val, *hash< auto > local_context)
 expands all variables in a hash with templated values More...
 
static hash< BbVariable > bbParseExactlyOneVariable (string str)
 parses one template variable and returns a hash with its parts More...
 
static auto getInputData (string field_name, *hash< auto > local_context, *hash< auto > input_data_cfg)
 returns specified input data field's value More...
 
static hash< auto > getInputData (*hash< auto > input_data_cfg, *hash< auto > local_context)
 returns all input data More...
 
static *hash< auto > updateHashDotValue (*hash< auto > var_data, string var_name, auto value)
 updates the given hash with a key in dot notation with the given value More...
 
static updateOutputData (string field_name, auto output_data, *hash< auto > output_data_cfg)
 updates specified output data field's value More...
 
static updateOutputData (hash< auto > all_output_data, hash< auto > output_data_cfg=UserApi::getConfigItemValue(BB_OUTPUT_DATA_CFG_KEY, NOTHING, False))
 updates all output data More...
 
static writeOutputData (*hash< auto > output_data)
 Writes output data using a concise format. More...
 
static string getTextFileFromLocation (string location)
 returns string data for the given file location More...
 
static binary getBinaryFileFromLocation (string location)
 returns binary data for the given file location More...
 
static Qore::StreamReader getStreamReaderFromLocation (string location)
 Returns a string stream for the file's data at the given location. More...
 
static Qore::InputStream getBinaryStreamFromLocation (string location)
 Returns an input stream for file data at the given location. More...
 
static writeFileToLocation (string location, data contents)
 Writes data to a file at the given location. More...
 
static FileLocationHandler::OutputStreamWrapper getOutputStreamForLocation (string location)
 Returns an output stream for writing data to the given location. More...
 
static auto executeFsm (string fsm_name, auto arg)
 Executes the given Finite State Machine and returns the final output. More...
 
static registerFsmAsObserver (string fsm_name, DataProvider::Observable observable, string event_id)
 Registers the given Finite State Machine with the given object as an Observer. More...
 
static string generateTokenForUser (string username, timeout expiry=DefaultTokenExpirationPeriod)
 Generates an access token for the given user with the given expiration time. More...
 
static string generateTokenForUser (string username, int expiry_seconds)
 Generates an access token for the given user with the given expiration time. More...
 
static bool invalidateToken (string token)
 Invalidates the given token. More...
 
static refreshToken (string token, *int expiry_seconds)
 Refreshes the given token. More...
 
static refreshToken (string token, timeout expiry_seconds)
 Refreshes the given token. More...
 
static *hash< TokenInfogetTokenInfo (string token, *bool refresh_token)
 Returns information for the given token. More...
 
static *hash< QorusUserInfogetCurrentUserInfo ()
 Returns information for the current user. More...
 
static hash< QorusUserInfogetUserInfo (string username)
 Returns information for the given user. More...
 
static public hash< auto > bindSubworkflow (hash< auto > wf, hash< auto > order)
 This method binds a workflow to a subworkflow step. More...
 
static public hash< auto > skipSubworkflow ()
 This method skips binding a workflow to a subworkflow step. More...
 
static public submitAsyncKey (string key)
 Binds the given key to the asynchronous step. More...
 
static public skipAsyncStep ()
 This method will skip the execution of an asynchronous step. More...
 
static public bindEvent (string eventkey)
 binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) More...
 
static public bindEventUnposted (string eventkey)
 binds a workflow synchronization event based on the event key to a workflow synchronization event step (type OMQ::ExecEvent) only if the event has not yet been posted; if the event has already been posted, then an ALREADY-POSTED exception is raised More...
 
static public skipEvent ()
 skips a workflow synchronization event step More...
 

Public Attributes

const ServiceCallContextKeys = ("socket", "socket-info", "peer-info", "url", "id", "ssl", "user", "client-cert")
 keys returned from the cx hash in getCallContext() if present More...
 

Additional Inherited Members

- Private Attributes inherited from OMQ::UserApi::UserApi
const DataProviderRootValues
 data provider root path values
 
const DataTypeRootValues
 data type root path values
 
const DataProviderPathTypeValues
 data type path provider type values
 

Detailed Description

primary service API class

Note
In Python available as svcapi

Member Function Documentation

◆ bindFtp()

static OMQ::UserApi::Service::ServiceApi::bindFtp ( OMQ::AbstractFtpHandler  handler)
static

binds an FTP handler to the service; listeners are started according to the listener information in the OMQ::AbstractFtpHandler argument

Parameters
handlerdefines parameters and callback routines for the system FTP server
Exceptions
SERVICE-FTP-ERRORno listeners set in OMQ::AbstractFtpHandler, error starting listener

◆ bindHandler() [1/2]

static OMQ::UserApi::Service::ServiceApi::bindHandler ( string  name,
HttpServer::AbstractHttpRequestHandler  handler,
string  url,
*softlist< auto >  content_type,
*softlist< auto >  special_headers,
bool  isregex = True 
)
inlinestatic

binds a new handler to a dedicated HTTP service listener by name

Parameters
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
urla regex for the URL to service
content_typean optional list of Content-Types to match
special_headersan optional list of special headers to match
isregexdefines if url is a regular expression or not

◆ bindHandler() [2/2]

static OMQ::UserApi::Service::ServiceApi::bindHandler ( string  name,
OMQ::AbstractServiceHttpHandler  handler 
)
static

binds a new handler to a dedicated HTTP service listener by name

Parameters
namethe name of the service resource for the dedicated service listener
handlerdefines parameters and callback routines for the system HTTP server
Exceptions
BIND-HANDLER-ERRORcannot bind a handler with listeners to an existing HTTP service handler

◆ bindHttp()

static list<string> OMQ::UserApi::Service::ServiceApi::bindHttp ( OMQ::AbstractServiceHttpHandler  handler,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

binds an HTTP handler to the service

If any listener information is present, then existing listeners with same bind value are reused or new listeners are started according to the listener information in the AbstractHttpHandler argument.

Parameters
handlerdefines parameters and callback routines for the system HTTP server
optsadditional options for the HTTP handler binding process
Returns
a list of service resource names bound to the service; multiple resource names are returned only if there are multiple listeners defined in the handler argument
Exceptions
SERVICE-HTTP-ERRORerror starting listener, error binding URL
LISTENER-SHARING-ERRORthere is already a listener with same bind value and either the service that started it does not allow sharing of it, or the allow_listener_sharing option is set to False
See also
OMQ::HttpBindOptionInfo

◆ callApiAsCurrentUser()

static auto OMQ::UserApi::Service::ServiceApi::callApiAsCurrentUser ( string  call,
softlist< auto >  args 
)
static

calls a system API with the argument list to the API method as a top-level argument to this method as the current user

Parameters
callthe full api method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list
argsany arguments to the method; if multiple argument should be passed to the method, use a list of arguments here
Returns
the return value of the method
Exceptions
UNKNOWN-API-CALLinvalid API method
INVALID-INTERNAL-API-CALLAPI may not be called internally (ex: omq.system.shutdown-wait())
See also

◆ checkAuthorization()

static OMQ::UserApi::Service::ServiceApi::checkAuthorization ( )
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also

◆ checkAuthorizationArgs()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationArgs ( softlist< string args)
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
argsthe list of permissions to check
Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also

◆ checkAuthorizationOr()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationOr ( )
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also

◆ checkAuthorizationOrArgs()

static OMQ::UserApi::Service::ServiceApi::checkAuthorizationOrArgs ( softlist< string args)
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
argsthe list of permissions to check
Exceptions
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also

◆ checkFsmAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkFsmAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of Finite State Machines; throws an exception if the user is not authorized

Parameters
idsa list of finite state machines to check
Exceptions
FSM-ACCESS-ERRORthe user does not have access to one or more of the given finite state machines
Since
Qorus 5.0

◆ checkFsmAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkFsmAccess ( string  name)
static

checks if the current user has access to the given single Finite State Machine; throws an exception if the user is not authorized

Parameters
namethe finite state machine to check
Exceptions
FSM-ACCESS-ERRORthe user does not have access to the given finite state machine
Since
Qorus 5.0

◆ checkJobAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkJobAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized

Parameters
idsa list of jobids to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to one or more of the given jobs

◆ checkJobAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkJobAccess ( softint  id)
static

checks if the current user has access to the given single job ID; throws an exception if the user is not authorized

Parameters
idthe jobid to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to the given job

◆ checkJobInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkJobInstanceAccess ( softstring  jiid)
static

checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized

Parameters
jiidthe job_instanceid to check
Exceptions
JOB-ACCESS-ERRORthe user does not have access to the given job

◆ checkMapperAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkMapperAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized

Parameters
idsa list of mapperids to check
Exceptions
MAPPER-ACCESS-ERRORthe user does not have access to one or more of the given mappers

◆ checkMapperAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkMapperAccess ( softint  id)
static

checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized

Parameters
idthe mapperid to check
Exceptions
MAPPER-ACCESS-ERRORthe user does not have access to the given mapper

◆ checkPipelineAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkPipelineAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of data pipelines; throws an exception if the user is not authorized

Parameters
idsa list of pipelines to check
Exceptions
PIPELINE-ACCESS-ERRORthe user does not have access to one or more of the given pipelines
Since
Qorus 5.0

◆ checkPipelineAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkPipelineAccess ( string  name)
static

checks if the current user has access to the given single data pipeline; throws an exception if the user is not authorized

Parameters
namethe pipeline to check
Exceptions
PIPELINE-ACCESS-ERRORthe user does not have access to the given pipeline
Since
Qorus 5.0

◆ checkQueueAccess()

static OMQ::UserApi::Service::ServiceApi::checkQueueAccess ( softint  queueid,
string  key 
)
static

checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized

Parameters
queueidthe queue ID to check
keythe key value in queue given by the first argument to check
Exceptions
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow

◆ checkServiceAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkServiceAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized

Parameters
idsa list of serviceids to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to one or more of the given services

◆ checkServiceAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkServiceAccess ( softint  id)
static

checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized

Parameters
idthe serviceid to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given service

◆ checkUserAuthorization()

static OMQ::UserApi::Service::ServiceApi::checkUserAuthorization ( string  user)
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also
Since
Qorus 5.1.20

◆ checkUserAuthorizationArgs()

static OMQ::UserApi::Service::ServiceApi::checkUserAuthorizationArgs ( string  user,
softlist< string args 
)
static

checks user authorization for all permissions passed to the method; throws an exception if the user is not authorized

If current user does not have all of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
argsthe list of permissions to check
Exceptions
USER-ERRORthe user is not loaded
AUTHORIZATION-ERRORno authentication information supplied or user does not have all required permissions
See also
Since
Qorus 5.1.20

◆ checkUserAuthorizationOr()

static OMQ::UserApi::Service::ServiceApi::checkUserAuthorizationOr ( string  user)
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also
Since
Qorus 5.1.20

◆ checkUserAuthorizationOrArgs()

static OMQ::UserApi::Service::ServiceApi::checkUserAuthorizationOrArgs ( string  user,
softlist< string args 
)
static

checks user authorization for at least one of list of permissions passed to the method; throws an exception if the user is not authorized

If current user does not have at least one of the given permissions, an exception is thrown.

If no user information is available (for instance, the call is internal), then authorization is automatically granted. If there are any authorization errors; an appropriate exception is thrown.

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
argsthe list of permissions to check
Exceptions
USER-ERRORthe user is not loaded
AUTHORIZATION-ERRORno authentication information supplied or user does not have any of the permissions given
See also
Since
Qorus 5.1.20

◆ checkUserFsmAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserFsmAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of Finite State Machines; throws an exception if the user is not authorized

Parameters
idsa list of finite state machines to check
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
FSM-ACCESS-ERRORthe user does not have access to one or more of the given finite state machines
Since
Qorus 5.1.20

◆ checkUserFsmAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserFsmAccess ( string  user,
string  name 
)
static

checks if the current user has access to the given single Finite State Machine; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
namethe finite state machine to check
Exceptions
USER-ERRORthe user is not loaded
FSM-ACCESS-ERRORthe user does not have access to the given finite state machine
Since
Qorus 5.1.20

◆ checkUserJobAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserJobAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of job IDs; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of jobids to check
Exceptions
USER-ERRORthe user is not loaded
JOB-ACCESS-ERRORthe user does not have access to one or more of the given jobs
Since
Qorus 5.1.20

◆ checkUserJobAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserJobAccess ( string  user,
softint  id 
)
static

checks if the current user has access to the given single job ID; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe jobid to check
Exceptions
USER-ERRORthe user is not loaded
JOB-ACCESS-ERRORthe user does not have access to the given job
Since
Qorus 5.1.20

◆ checkUserJobInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkUserJobInstanceAccess ( string  user,
softstring  jiid 
)
static

checks if the current user has access to the given job_instanceid; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
jiidthe job_instanceid to check
Exceptions
USER-ERRORthe user is not loaded
JOB-ACCESS-ERRORthe user does not have access to the given job
Since
Qorus 5.1.20

◆ checkUserMapperAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserMapperAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of mapper IDs; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of mapperids to check
Exceptions
USER-ERRORthe user is not loaded
MAPPER-ACCESS-ERRORthe user does not have access to one or more of the given mappers
Since
Qorus 5.1.20

◆ checkUserMapperAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserMapperAccess ( string  user,
softint  id 
)
static

checks if the current user has access to the given single mapper ID; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe mapperid to check
Exceptions
USER-ERRORthe user is not loaded
MAPPER-ACCESS-ERRORthe user does not have access to the given mapper
Since
Qorus 5.1.20

◆ checkUserPipelineAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserPipelineAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of data pipelines; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idsa list of pipelines to check
Exceptions
USER-ERRORthe user is not loaded
PIPELINE-ACCESS-ERRORthe user does not have access to one or more of the given pipelines
Since
Qorus 5.1.20

◆ checkUserPipelineAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserPipelineAccess ( string  user,
string  name 
)
static

checks if the current user has access to the given single data pipeline; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
namethe pipeline to check
Exceptions
USER-ERRORthe user is not loaded
PIPELINE-ACCESS-ERRORthe user does not have access to the given pipeline
Since
Qorus 5.1.20

◆ checkUserQueueAccess()

static OMQ::UserApi::Service::ServiceApi::checkUserQueueAccess ( string  user,
softint  queueid,
string  key 
)
static

checks if the current user has access to the given queue entry (as determined through the workflow access list); throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
queueidthe queue ID to check
keythe key value in queue given by the first argument to check
Exceptions
USER-ERRORthe user is not loaded
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow
Since
Qorus 5.1.20

◆ checkUserServiceAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserServiceAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of serviceids; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of serviceids to check
Exceptions
USER-ERRORthe user is not loaded
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to one or more of the given services
Since
Qorus 5.1.20

◆ checkUserServiceAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserServiceAccess ( string  user,
softint  id 
)
static

checks if the current user has access to the given single serviceid; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe serviceid to check
Exceptions
USER-ERRORthe user is not loaded
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given service
Since
Qorus 5.1.20

◆ checkUserVmapAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserVmapAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idsa list of value map ids to check
Exceptions
USER-ERRORthe user is not loaded
VMAP-ACCESS-ERRORthe user does not have access to one or more of the given value maps
Since
Qorus 5.1.20

◆ checkUserVmapAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserVmapAccess ( string  user,
softint  id 
)
static

checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idthe value map id to check
Exceptions
USER-ERRORthe user is not loaded
VMAP-ACCESS-ERRORthe user does not have access to the given value map
Since
Qorus 5.1.20

◆ checkUserWorkflowAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkUserWorkflowAccess ( string  user,
list< auto >  ids 
)
static

checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized

Parameters
idsa list of workflowids to check
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
WORKFLOW-ACCESS-ERRORthe user does not have access to one or more of the given workflows
Since
Qorus 5.1.20

◆ checkUserWorkflowAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkUserWorkflowAccess ( string  user,
softint  id 
)
static

checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized

Parameters
idthe workflowid to check
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
WORKFLOW-ACCESS-ERRORthe user does not have access to the given workflow
Since
Qorus 5.1.20

◆ checkUserWorkflowInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkUserWorkflowInstanceAccess ( string  user,
softstring  wfiid 
)
static

checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
wfiidthe workflow_instanceid to check
Exceptions
USER-ERRORthe user is not loaded
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow
Since
Qorus 5.1.20

◆ checkVmapAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkVmapAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of value map IDs; throws an exception if the user is not authorized

Parameters
idsa list of value map ids to check
Exceptions
VMAP-ACCESS-ERRORthe user does not have access to one or more of the given value maps

◆ checkVmapAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkVmapAccess ( softint  id)
static

checks if the current user has access to the given single value map ID; throws an exception if the user is not authorized

Parameters
idthe value map id to check
Exceptions
VMAP-ACCESS-ERRORthe user does not have access to the given value map

◆ checkWorkflowAccess() [1/2]

static OMQ::UserApi::Service::ServiceApi::checkWorkflowAccess ( list< auto >  ids)
static

checks if the current user has access to the given list of workflow IDs; throws an exception if the user is not authorized

Parameters
idsa list of workflowids to check
Exceptions
WORKFLOW-ACCESS-ERRORthe user does not have access to one or more of the given workflows

◆ checkWorkflowAccess() [2/2]

static OMQ::UserApi::Service::ServiceApi::checkWorkflowAccess ( softint  id)
static

checks if the current user has access to the given single workflow ID; throws an exception if the user is not authorized

Parameters
idthe workflowid to check
Exceptions
WORKFLOW-ACCESS-ERRORthe user does not have access to the given workflow

◆ checkWorkflowInstanceAccess()

static OMQ::UserApi::Service::ServiceApi::checkWorkflowInstanceAccess ( softstring  wfiid)
static

checks if the current user has access to the given workflow_instanceid; throws an exception if the user is not authorized

Parameters
wfiidthe workflow_instanceid to check
Exceptions
WORKFLOW-ACCESS-ERRORno authentication information supplied or user does not have access to the given workflow

◆ generateTokenCheckUser() [1/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenCheckUser ( string  username,
int  expire_seconds 
)
static

Generates an authentication token for the given user.

Parameters
usernamethe user to log in
expire_secondsthe validity period for the token
Returns
an authentication token for the given user

It is assumed that the user has already been authenticated externally; no user authentication is performed in this call.

Exceptions
USER-ERRORthe given user is invalid; authentication tokens can only be generated for valid users
See also
Since
Qorus 5.1.20

◆ generateTokenCheckUser() [2/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenCheckUser ( string  username,
timeout  expiry 
)
static

Generates an authentication token for the given user.

Parameters
usernamethe user to log in
expirythe validity period for the token with a resolution of 1 second
Returns
an authentication token for the given user

It is assumed that the user has already been authenticated externally; no user authentication is performed in this call.

Exceptions
USER-ERRORthe given user is invalid; authentication tokens can only be generated for valid users
See also
Since
Qorus 5.1.20

◆ generateTokenForCurrentUser() [1/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenForCurrentUser ( int  expiry_seconds)
static

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

Parameters
expiry_secondsthe expiration time of the token
Returns
the new token for the current user
Since
Qorus 5.1.1

◆ generateTokenForCurrentUser() [2/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenForCurrentUser ( timeout  expiry = DefaultTokenExpirationPeriod)
static

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

Parameters
expirythe expiration time of the token with a resolution of one second
Returns
the new token for the current user
Since
Qorus 5.1.1

◆ generateTokenLoginUser() [1/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenLoginUser ( string  username,
int  expire_seconds,
reference< hash< auto >>  cx 
)
static

Generates an authentication token for the given user and logs the user in for the existing connection context.

Parameters
usernamethe user to log in
expire_secondsthe validity period for the token
cxa reference to an HTTP call context hash
Returns
an authentication token for the given user

It is assumed that the user has already been authenticated externally; no user authentication is performed in this call.

Exceptions
USER-ERRORthe given user is invalid; authentication tokens can only be generated for valid users
See also
Since
Qorus 5.1.20

◆ generateTokenLoginUser() [2/2]

static string OMQ::UserApi::Service::ServiceApi::generateTokenLoginUser ( string  username,
timeout  expiry,
reference< hash< auto >>  cx 
)
static

Generates an authentication token for the given user and logs the user in for the existing connection context.

Parameters
usernamethe user to log in
expirythe validity period for the token with a resolution of 1 second
cxa reference to an HTTP call context hash
Returns
an authentication token for the given user

It is assumed that the user has already been authenticated externally; no user authentication is performed in this call.

Exceptions
USER-ERRORthe given user is invalid; authentication tokens can only be generated for valid users
See also
Since
Qorus 5.1.20

◆ getActiveJobsAsCurrentUser()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getActiveJobsAsCurrentUser ( )
static

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

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

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

◆ getCallContext()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getCallContext ( )
static

returns contextual information about the current call

Returns
NOTHING if no context information is available, otherwise a hash with the following possible keys; keys actually present depend on the context of the caller to the service method:
  • wf: this key is present if the call to the service method originated from workflow code while processing an order; the value is a hash with the following keys:
    • name: the name of the workflow
    • version: the version of the workflow
    • workflowid: the workflowid of the workflow
    • workflow_instanceid: the workflow_instanceid of the order being executed
    • stepid: the stepid of the step being executed
    • ind: the array step index of the step being executed
    • priority: the priority of the workflow order
    • started: the date/time the order started processing
    • options: the current workflow execution instance option hash
  • job: this key is present if the call to the service method originated from job code; the value is a hash with the following keys:
    • jobid: the metadata jobid of the job type
    • job_instanceid: the id of the job instance
    • name: the job name
    • version: the job version
    • description: the job description
    • trigger: a string describing the timer/trigger for the job
    • last_executed: the last executed date/time of the job (NOTHING if never executed before the current iteration)
    • last_executed_job_instanceid: the last executed instance id of the job
    • next: the next trigger date/time
  • cx: this key is present if the call to the service method originated externally through the network API; the value is a hash with the following keys:
    • client-cert: an SSLCertificate object for the client certificate if client certificate capture has been enabled in the listener (see the get_remote_certs key in HttpListenerOptionInfo)
    • id: the unique HTTP connection ID
    • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
    • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
    • socket-info: a hash of socket information for the listening socket (as returned by Socket::getSocketInfo())
    • ssl: True if the request was encrypted with HTTPS, False if not
    • url: a hash of broken-down URL information (as returned from parseURL())
    • user: the current RBAC username (if any)
See also

◆ getCallContextString()

static string OMQ::UserApi::Service::ServiceApi::getCallContextString ( *hash< auto >  cx)
static

returns a string describing the current call context

Example:
string str = ServiceApi::getCallContextString();
Parameters
cxoptional thread context hash from HTTP handler if available
Returns
a string describing the current call context

◆ getConfigItemHash()

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

returns a hash of all configuration items for the current service

Example:
hash<auto> config = ServiceApi::getConfigItemHash();
Parameters
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see UserApi::getUserContextInfo() method)
Returns
a hash of all configuration items for the current service; keys are config item names; values are config item values. If there are no config items for the current service, then an empty hash is returned.
Note
if there are local configuration item values and values on global level, the local values will take precedence over the global values
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
values are always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
See also
Service Configuration Items

◆ getConfigItemValue()

static auto OMQ::UserApi::Service::ServiceApi::getConfigItemValue ( string  item,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
static

returns the value of the given service configuration item

Example:
auto val = ServiceApi::getConfigItemValue(item);
Parameters
itemthe name of the service configuration item; service configuration item values take precedence over values on global level if both are set otherwise if both are not set the default value is returned
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see the UserApi::getUserContextInfo() method)
expand_complex_valuesif True then lists and hashes will have their string values expanded recursively
Returns
the value of the given configuration item
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
Since
  • Qorus 4.1.1 added the expand_complex_values parameter
See also
Service Configuration Items

◆ getFsmAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getFsmAccessHash ( )
static

returns a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all finite state machines

Returns
a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no finite state machines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.0

◆ getFsmAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getFsmAccessList ( )
static

returns a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all finite state machines

Returns
a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no finite state machines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.0

◆ getHttpCallContext()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getHttpCallContext ( )
static

returns a hash with HTTP call context information

Note
This API method is relevant for any external HTTP call, including SOAP and REST calls

◆ getJobAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getJobAccessHash ( )
static

returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all jobs

Returns
a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

◆ getJobAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getJobAccessList ( )
static

returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all jobs

Returns
a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

◆ getLastEvents()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEvents ( softint  count)
static

returns the last system events

Parameters
countthe maximum number of system events to return
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned

◆ getLastEventsAnd()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEventsAnd ( softint  count,
auto  filter,
auto  or_not 
)
static

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

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned

◆ getLastEventsOr()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getLastEventsOr ( softint  count,
auto  filter,
auto  and_not 
)
static

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

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

Parameters
countthe maximum number of events to return; if this argument is 0, then the size of the returned list is only limited by the number of events in the system that match the filter(s) passed.
filterthis argument gives the criteria list for "logical or" comparisons to be applied to the events. If an event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional third argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the third argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the third argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-LAST-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned

◆ getMapperAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getMapperAccessHash ( )
static

returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Returns
a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

◆ getMapperAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getMapperAccessList ( )
static

returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Returns
a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

◆ getOption()

static auto OMQ::UserApi::Service::ServiceApi::getOption ( )
static

Returns the value of the named service option(s)

If the option is not set on the service level, and it is a valid system option, then the value of the system

option will be returned.

Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if no arguments are passed to the method all service-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getOptionArgs()

static auto OMQ::UserApi::Service::ServiceApi::getOptionArgs ( *softlist< string args)
static

Returns the value of the named service option or options.

If the option is not set on the service, and it is a valid system option, then the value of the system

option will be returned.

Parameters
argsthe list of options to return
Returns
the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if no arguments are passed to the method all service-level options are returned as a hash
Note
Invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
See also

◆ getPipelineAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getPipelineAccessHash ( )
static

returns a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all pipelines

Returns
a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no pipelines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.0

◆ getPipelineAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getPipelineAccessList ( )
static

returns a list of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all pipelines

Returns
a list of datapipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no pipelines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.0

◆ getResource()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getResource ( string  name,
hash< auto >  ctx,
int  code = 200,
*hash< auto >  hdr 
)
static

Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
hash<auto> h = ServiceApi::getResource("image.jpg", cx);
Parameters
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getResourceData()

static data OMQ::UserApi::Service::ServiceApi::getResourceData ( string  name,
*hash< auto >  ctx 
)
static

Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
binary img = ServiceApi::getResourceData("image.jpg");
Parameters
namethe name of the file resource
ctxan optional argument hash used if rendering a template resource
Returns
the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getResourceHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getResourceHash ( )
static

returns a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none

Example:
*hash<auto> h = ServiceApi::getResourceHash();
Returns
a hash of the service's file resources (hash keys are service file resource names) or NOTHING if the service has none
See also

◆ getResourceList()

static list<string> OMQ::UserApi::Service::ServiceApi::getResourceList ( )
static

returns a list of the service's file resources or NOTHING if the service has none

Example:
list<auto> l = ServiceApi::getResourceList();
Returns
a list of the service's file resources or NOTHING if the service has none
See also

◆ getResourceWsdl()

static WSDL::WebService OMQ::UserApi::Service::ServiceApi::getResourceWsdl ( string  name,
*hash< auto >  ctx 
)
static

Returns the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned, if the given resource does not exist, then an exception is raised.

Example:
WebService wsdl = ServiceApi::getResourceWsdl("interface1.wsdl");
Parameters
namethe name of the file resource representing the WSDL source
ctxan optional argument hash used if rendering a template resource
Returns
the given file resource as a WSDL::WebService object; any XSD imports are resolved as service resources; if a template exists, then the template is rendered and returned
Exceptions
SERVICE-FILE-RESOURCE-ERRORthe given service file resource does not exist
See also

◆ getRunningWorkflowListAsCurrentUser()

static list<hash<auto> > OMQ::UserApi::Service::ServiceApi::getRunningWorkflowListAsCurrentUser ( string  name,
*string  ver 
)
static

returns a list of hashes giving information about the currently-running workflow execution instances if the current user can access them

Returns
a list of hashes giving information about the currently-running workflow execution instances; if no workflow execution instances are running, then an empty list is returned; otherwise each list element is a hash with the following keys:
  • executionID: the workflow execution instance id

    Exceptions
    WORKFLOW-ACCESS-ERRORthe current user does not have the right to access one or more running workflows

◆ getServiceAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceAccessHash ( )
static

returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

NOTHING is only returned if the current user has access to all services

Returns
a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

◆ getServiceAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getServiceAccessList ( )
static

returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

NOTHING is only returned if the current user has access to all services

Returns
a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

◆ getServiceInfo()

static hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfo ( *hash< auto >  cx)
static

returns information about the current service

Parameters
cxoptional thread context hash from HTTP handler if available
Returns
a hash with the following keys:
  • type: the service type ("user" or "system")
  • name: the name of the service
  • version: the version of the service
  • desc: the description of the service
  • serviceid: the ID of the service, corresponding to SERVICES.SERVICEID in the database
  • status: either OMQ::SSRunning (if there are running threads) or OMQ::SSLoaded
  • threads: the number of currently running threads
  • autostart: the autostart flag
  • loaded: the date/time the service was loaded/started
  • methods: a list of hashes with name and desc keys for each method
  • method: the name of the current method being called
  • resources: a hash of resources attached to the service (may be NOTHING); each hash key is the unique resource name, and the value of each key is a hash with the following keys:
    • type: a string giving the resource type name (ie "HttpGlobalHandler", "HttpListener", "FtpListener", etc)
    • desc: a hashdecl description of the resource
    • info: a hash with additional, free-form information about the resource
  • groups: a list of zero or more strings giving group names the service is a member of

◆ getServiceInfoAsCurrentUser() [1/2]

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfoAsCurrentUser ( softint  id,
*hash< auto >  cx 
)
static

returns information about the given service from the serviceid (if it's currently loaded) and if the calling user can access the service

to get information about services whether they are loaded or not, call REST API:

system/metadata/lookupserviceinfo/<type>/<name>
Parameters
idthe serviceid of the service
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service

◆ getServiceInfoAsCurrentUser() [2/2]

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getServiceInfoAsCurrentUser ( string  type,
string  name,
*hash< auto >  cx 
)
static

returns information about the given service from the service name (if it's currently loaded) and if the calling user can access the service

to get information about services whether they are loaded or not, call REST API:

system/metadata/lookupserviceinfo/<type>/<name>
Parameters
typethe type of service (either "system" or "user"; case is ignored)
namethe name of the system service to query
cxoptional thread context hash from HTTP handler if available
Returns
a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:
  • type: either "system" or "user" corresponding to the argument
  • name: the name of the service
  • version: version of the service
  • desc: description of the service
  • serviceid: service ID
  • status: OMQ::SSRunning or OMQ::SSLoaded
  • threads: number of running threads in the service
  • autostart: True or False if the autostart flag is set
  • loaded: date/time the service was loaded
  • methods: list of hashes for each method with name and desc keys
  • processes: list of process info hashes for remote services
Exceptions
SERVICE-ACCESS-ERRORthe current user does not have the right to access the given service

◆ getStateData()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getStateData ( )
static

returns any service state state data stored with saveStateData()

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

◆ getTemplateHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getTemplateHash ( )
static

returns a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none

Example:
*hash<auto> h = ServiceApi::getTemplateHash();
Returns
a hash of the service's template file resources (hash keys are service template resource names) or NOTHING if the service has none
See also

◆ getTemplateList()

static list<string> OMQ::UserApi::Service::ServiceApi::getTemplateList ( )
static

returns a list of the service's template file resources or NOTHING if the service has none

Example:
list<auto> l = ServiceApi::getTemplateList();
Returns
a list of the service's template file resources or NOTHING if the service has none
See also

◆ getUserFsmAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserFsmAccessHash ( string  user)
static

returns a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all finite state machines

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a hash of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty hash means that the user has access to no finite state machines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.1.20

◆ getUserFsmAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserFsmAccessList ( string  user)
static

returns a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all finite state machines

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a list of Finite State Machines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty list means that the user has access to no finite state machines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.1.20

◆ getUserJobAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserJobAccessHash ( string  user)
static

returns a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown NOTHING is only returned if the current user has access to all jobs

Returns
a hash of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getUserJobAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserJobAccessList ( string  user)
static

returns a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown NOTHING is only returned if the current user has access to all jobs

Returns
a list of job IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getUserMapperAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserMapperAccessHash ( string  user)
static

returns a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a hash of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
Since
Qorus 5.1.20

◆ getUserMapperAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserMapperAccessList ( string  user)
static

returns a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all mappers

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a list of mapper IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
Since
Qorus 5.1.20

◆ getUserPipelineAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserPipelineAccessHash ( string  user)
static

returns a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all pipelines

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a hash of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty hash means that the user has access to no pipelines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.1.20

◆ getUserPipelineAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserPipelineAccessList ( string  user)
static

returns a list of data pipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all pipelines

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a list of datapipelines the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty list means that the user has access to no pipelines; this must be distinguished from a return value of NOTHING, which means that the user has access to all finite state machines
Since
Qorus 5.1.20

◆ getUserServiceAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserServiceAccessHash ( string  user)
static

returns a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown NOTHING is only returned if the current user has access to all services

Returns
a hash of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getUserServiceAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserServiceAccessList ( string  user)
static

returns a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown NOTHING is only returned if the current user has access to all services

Returns
a list of service IDs the current user has access to; or, if the current user has access to all services, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getUserVmapAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserVmapAccessHash ( string  user)
static

returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
Since
Qorus 5.1.20

◆ getUserVmapAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserVmapAccessList ( string  user)
static

returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps
Since
Qorus 5.1.20

◆ getUserWorkflowAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getUserWorkflowAccessHash ( string  user)
static

returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getUserWorkflowAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getUserWorkflowAccessList ( string  user)
static

returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ getVmapAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getVmapAccessHash ( )
static

returns a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Returns
a hash of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty hash means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

◆ getVmapAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getVmapAccessList ( )
static

returns a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all value maps

Returns
a list of value map IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned
Note
a return value of an empty list means that the user has access to no value maps; this must be distinguished from a return value of NOTHING, which means that the user has access to all value maps

◆ getWorkflowAccessHash()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::getWorkflowAccessHash ( )
static

returns a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Returns
a hash of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

◆ getWorkflowAccessList()

static *list<auto> OMQ::UserApi::Service::ServiceApi::getWorkflowAccessList ( )
static

returns a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

NOTHING is only returned if the current user has access to all workflows

Returns
a list of workflow IDs the current user has access to; or, if the current user has a role with the DEFAULT group, then NOTHING is returned

◆ hasResource()

static bool OMQ::UserApi::Service::ServiceApi::hasResource ( string  name)
static

returns True if the given service file resource exists, False if not

Example:
bool b = ServiceApi::hasResource(name);
Returns
True if the given service file resource exists, False if not
See also

◆ hasTemplate()

static bool OMQ::UserApi::Service::ServiceApi::hasTemplate ( string  name)
static

returns True if the given service template file resource exists, False if not

Example:
bool b = ServiceApi::hasTemplate(name);
Returns
True if the given service template file resource exists, False if not
See also

◆ persistenceRegister()

static OMQ::UserApi::Service::ServiceApi::persistenceRegister ( code  factory)
static

registers the service as providing persistent/dedicated HTTP connection support

Example:
ServiceApi::persistenceRegister(code);
Parameters
factorya closure or call reference that returns a persistence tracking object derived from OMQ::AbstractPersistentDataHelper, takes the following args: hash&lt:auto> cx, *hash<auto> ah
Exceptions
SERVICE-PERSISTENCE-ERRORa persistence handler has already been registered

◆ persistenceThreadTerminate()

static OMQ::UserApi::Service::ServiceApi::persistenceThreadTerminate ( )
static

terminates a persistent connection in the current thread

Example:
ServiceApi::persistenceThreadTerminate();
Exceptions
SERVICE-PERSISTENCE-ERRORthe current thread is not in a persistent connection

◆ registerSoapHandler()

static OMQ::UserApi::Service::ServiceApi::registerSoapHandler ( hash< auto >  h)
static

registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol

Creates a mapping in the system SoapHandler from the given WSDL to the current service. SOAP operations defined in the WSDL will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
ha hash with the following keys (only wsdl or wsdl_file is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • uri_path: an optional string giving an optional URI path to use when binding the SOAP service
Exceptions
REGISTER-SOAP-HANDLER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash

◆ registerSoapListener()

static list<string> OMQ::UserApi::Service::ServiceApi::registerSoapListener ( hash< auto >  sh,
softstring  bind,
int  family = AF_UNSPEC,
*HttpServer::AbstractAuthenticator  auth,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

starts a dedicated SOAP listener with the given WSDL and registers the current service as a SOAP service and exports its methods that map to SOAP operations in the given WSDL to be called from the Qorus HttpServer with the SOAP protocol

Example:
hash opts.wsdl = ServiceApi::getResourceData("MySoapService.wsdl");
list ret = ServiceApi::registerSoapListener(opts, port);
logInfo("soap listeners: %y", ret);

Creates a mapping in the system SoapHandler from the given WSDL to the current service. SOAP operations defined in the WSDL will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
sha hash with the following keys (only wsdl, wsdl_file, or wsdl_resource is required)):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
See also

◆ registerSoapListeners()

static list<string> OMQ::UserApi::Service::ServiceApi::registerSoapListeners ( list< auto >  sl,
softstring  bind,
*hash< auto >  lh,
int  family = AF_UNSPEC,
*HttpServer::AbstractAuthenticator  auth,
hash< HttpBindOptionInfo opts = HttpBindOptionInfo >{} 
)
static

starts a dedicated SOAP listener with one or more WSDLs and registers the current service as a SOAP service and exports all methods that map to SOAP operations in the given WSDLs to be called from the Qorus HttpServer with the SOAP protocol

Example:
list<hash<auto>> sl = (
{"wsdl": ServiceApi::getResourceData("MySoapService1.wsdl"},
{"wsdl": ServiceApi::getResourceData("MySoapService2.wsdl"},
);
list<auto> ret = ServiceApi::registerSoapListeners(sl, port);
logInfo("soap listeners: %y", ret);

Creates a mapping in the system SoapHandler from the given WSDLs to the current service. SOAP operations defined in the WSDLs will be mapped directly to Qorus service methods with the same names as the SOAP operations.

Parameters
sla list of hashes with the following keys (only wsdl, wsdl_file, or wsdl_resource is required):
  • wsdl, wsdl_file, or wsdl_resource: a URL to the WSDL, the WSDL string (XSD), a WebService object, or a file resource name giving the WSDL file
  • service: a string giving the name of the SOAP service to map to this service; this key is only necessary to set if the WSDL defines multiple SOAP services
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
lhan optional hash of listener info for HTTPS listeners
  • cert_path: (optional) a path to an X509 certificate for HTTPS listeners
  • key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners
  • key_password: (optional) an optional string giving the password for the private key (PEM format only)
  • cert: (optional) a Qore::SSLCertificate object for HTTPS listeners
  • key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
authif NOTHING then the system authenticator is used, otherwise an authenticator object for the listener; to authenticate all requests, use an object of class PermissiveAuthenticator
optsadditional options for the HTTP handler binding process
Returns
a list of resource names for the HTTP listener resources added to the service
Exceptions
REGISTER-SOAP-LISTENER-ERRORmissing wsdl or wsdl_file key in argument hash; cannot find service; multiple services defined by WSDL but no service key given in argument hash
See also

◆ renderTemplate()

static hash<auto> OMQ::UserApi::Service::ServiceApi::renderTemplate ( string  name,
hash< auto >  ctx 
)
static

explicitly renders a template file resource given the template argument hash

Example:
hash<auto> h = ServiceApi::renderTemplate("html/index.qhtml", ctx);
Parameters
namethe template file resource name
ctxthe argument hash to the template code
Returns
a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
Exceptions
TEMPLATE-ERRORthe named template does not exist
See also

◆ saveStateData()

static OMQ::UserApi::Service::ServiceApi::saveStateData ( *hash< auto >  data)
static

serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA

Parameters
datathe state data to serialize and store against the service's state data in SERVICE_STATE_DATA
See also

◆ saveStateDataPath()

static OMQ::UserApi::Service::ServiceApi::saveStateDataPath ( string  path,
auto  value 
)
static

serializes the given hash and stores against the service's state data in SERVICE_STATE_DATA

# will assign {"account": {"id": "123456ABC"}}
ServiceApi::saveStateDataPath("account.id", "123456ABC");
Parameters
paththe path to the data to save
valuethe value to merge into existing persistent state data at the given path
See also
Since
Qorus 5.0

◆ setConfigItemChangeCallback()

static OMQ::UserApi::Service::ServiceApi::setConfigItemChangeCallback ( *code  callback)
static

Set a callback for config item value changes in the service.

Example:
class MyService inherits QorusService {
private:internal myCallback(string config_item_name) {
# ...
}
init() {
setConfigItemChangeCallback(\myCallback());
}
}
Parameters
callbackthe callback in the service; must take a single string argument giving the name of the config item whose value was updated
Note
The callback is executed asynchronously to the update; there can be a lag between the actual update and the delivery of the message from qorus-core to the remote process (if the interface is running remotely), also the callback is always run in a background thread that is unsynchronized with the change of the config item value; keep these facts in mind when writing code that reacts to config item value updates.
Since
Qorus 4.1

◆ setOption() [1/2]

static OMQ::UserApi::Service::ServiceApi::setOption ( hash< auto >  opts)
static

Changes option values on a service.

If at least one invalid option is passed to the method, an exception will be raised; however all other valid

options in the hash will be set before the exception is raised

Parameters
optsa hash of option-value pairs
Exceptions
SERVICE-OPTION-ERRORinvalid option name
See also

◆ setOption() [2/2]

static OMQ::UserApi::Service::ServiceApi::setOption ( string  option,
auto  value 
)
static

Changes a single option value on a service.

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

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

◆ setUserLoginContextFromToken()

static OMQ::UserApi::Service::ServiceApi::setUserLoginContextFromToken ( string  token,
reference< hash< auto >>  cx 
)
static

Sets the user login context from the given token.

Parameters
tokenan authentication token for an existing user
cxa reference to an HTTP call context hash

Sets thread local data and updates the call context hash argument for the user identified by token; also refreshes the token's expiration time.

Exceptions
TOKEN-ERRORthe given authentication token is not valid
Since
Qorus 5.1.20

◆ sleep()

static int OMQ::UserApi::Service::ServiceApi::sleep ( softint  arg)
static

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

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or usleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of seconds to sleep
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ startListeners()

static list<hash<auto> > OMQ::UserApi::Service::ServiceApi::startListeners ( softstring  bind,
*string  cert_path,
*string  key_path,
*string  key_password,
*string  name,
int  family = AF_UNSPEC 
)
inlinestatic

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

Parameters
bindthe bind address of the new listener; listeners will be started on all possible bind addresses in case more than one interface is resolved from the bind address given
cert_paththe file name of the X.509 certificate in PEM format (only for HTTPS listeners)
key_paththe file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
key_passwordthe optional password for the private key
namean optional name prefix for the listener; the final listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
familyone of the following network family constants:
  • AF_INET: for binding an IPv4 socket
  • AF_INET6: for binding an IPv6 socket
  • AF_UNSPEC: for binding a socket with any available address family
Returns
a list of hashes for each listener started, each hash having the following keys (note that for UNIX domain socket listeners the hostname, hostname_desc, and port keys will not be present):
  • hostname: the hostname of the interface
  • hostname_desc: a descriptive string for the hostname including the address family (ex: "ipv6[localhost]")
  • address: the address of the listener (i.e. "192.168.30.4", etc)
  • address_desc: a descriptive string for the hostname including the address family (ex: "ipv6[::1]")
  • port: the port number
  • family: an integer giving the address family (AF_INET, AF_INET6, AF_UNIX, etc)
  • familystr: a string describing the address family (ex: "ipv6")
  • proto: either "http" or "https"
  • id: the Qorus ID of the listener
  • bind: a string giving the bind address used (ex: "127.0.0.1:8001")
Note
listeners started with this API will be served by global Qorus HTTP handlers; they will not be added as service-specific listeners
See also

◆ startThread()

static int OMQ::UserApi::Service::ServiceApi::startThread ( auto  code)
static

starts a service thread; passes the remaining arguments to the function to the new thread

Parameters
codethe function or service method to call; may be a string giving a function name (string), a call reference, or a closure
Returns
the TID of the new thread
Exceptions
START-SERVICE-THREAD-ERRORthe service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)

◆ startThreadArgs()

static int OMQ::UserApi::Service::ServiceApi::startThreadArgs ( auto  code,
auto  args 
)
static

starts a service thread; uses the second argument as the argument list to pass to the new thread

Parameters
codethe function or service method to call; may be a string giving a function name (string), a call reference, or a closure
argsthe arguments for the function to start in the separate thread
Returns
the TID of the new thread
Exceptions
START-SERVICE-THREAD-ERRORthe service has no "stop()" method or too many threads are already active in this service (see qorus.max-service-threads)

◆ stopListener()

static OMQ::UserApi::Service::ServiceApi::stopListener ( softstring  name)
static

stops a single listener based on its name or bind address; does not return until all connections on the listener have closed

See also

◆ stopListenerId()

static OMQ::UserApi::Service::ServiceApi::stopListenerId ( softint  id)
static

stops a single listener based on its listener ID; does not return until all connections on the listener have closed

See also

◆ streamRegister()

static OMQ::UserApi::Service::ServiceApi::streamRegister ( string  name,
softlist< string methods,
code  factory,
string  desc 
)
static

registers an HTTP chunked data handler as a service resource

Example:
ServiceApi::streamRegister("stream", "GET", factory, "returns a data stream with log information");
Parameters
namethe name of the stream handler
methodsone or more HTTP methods acceptable for this stream; when acquired with other methods, a 405 Method Not Allowed response is returned
factorya closure or call reference that returns an AbstractRestStreamRequestHandler object, takes the following args: hash&lt:auto> cx, *hash<auto> ah
desca description for the stream

◆ testAuthorization()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorization ( )
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Returns
if current user does not have all of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationArgs()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationArgs ( softlist< string args)
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
argsthe list of permissions to test
Returns
if current user does not have all of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationOr()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationOr ( )
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
See also

◆ testAuthorizationOrArgs()

static bool OMQ::UserApi::Service::ServiceApi::testAuthorizationOrArgs ( softlist< string args)
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
argsthe list of permissions to test
Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
See also

◆ testFsmAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testFsmAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of Finite State Machines and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of finite state machines to check
Since
Qorus 5.0

◆ testFsmAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testFsmAccess ( string  name)
static

tests if the current user has access to the given single Finite State Machine and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
namethe finite state machine to check
Since
Qorus 5.0

◆ testJobAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testJobAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of jobids to check

◆ testJobAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testJobAccess ( softint  id)
static

tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe jobid to check

◆ testMapperAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testMapperAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of mapperids to check

◆ testMapperAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testMapperAccess ( softint  id)
static

tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe mapperid to check

◆ testPipelineAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testPipelineAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of data pipelines and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of pipelines to check
Since
Qorus 5.0

◆ testPipelineAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testPipelineAccess ( string  name)
static

tests if the current user has access to the given single data pipeline and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
namethe pipeline to check
Since
Qorus 5.0

◆ testServiceAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testServiceAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of serviceids to check
Exceptions
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given services

◆ testServiceAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testServiceAccess ( softint  id)
static

tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe serviceid to check

◆ testUserAuthorization()

static bool OMQ::UserApi::Service::ServiceApi::testUserAuthorization ( string  user)
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
if current user does not have all of the given permissions, returns False, otherwise True.
Exceptions
USER-ERRORthe user is not loaded
See also
Since
Qorus 5.1.20

◆ testUserAuthorizationArgs()

static bool OMQ::UserApi::Service::ServiceApi::testUserAuthorizationArgs ( string  user,
softlist< string args 
)
static

tests user authorization for all of permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
argsthe list of permissions to test
Returns
if current user does not have all of the given permissions, returns False, otherwise True.
Exceptions
USER-ERRORthe user is not loaded
See also
Since
Qorus 5.1.20

◆ testUserAuthorizationOr()

static bool OMQ::UserApi::Service::ServiceApi::testUserAuthorizationOr ( string  user)
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
Exceptions
USER-ERRORthe user is not loaded
See also
Since
Qorus 5.1.20

◆ testUserAuthorizationOrArgs()

static bool OMQ::UserApi::Service::ServiceApi::testUserAuthorizationOrArgs ( string  user,
softlist< string args 
)
static

tests user authorization for at least one of the permissions passed to the method and returns True (if authorization is granted) or False (if the user is not authorized)

If no user information is available (for instance, the call is internal), then authorization is automatically granted.

If there are any authorization errors, the method returns False

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
argsthe list of permissions to test
Returns
if current user does not have at least one of the given permissions, returns False, otherwise True.
Exceptions
USER-ERRORthe user is not loaded
See also
Since
Qorus 5.1.20

◆ testUserFsmAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserFsmAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of Finite State Machines and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idsa list of finite state machines to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserFsmAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserFsmAccess ( string  user,
string  name 
)
static

tests if the current user has access to the given single Finite State Machine and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
namethe finite state machine to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserJobAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserJobAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of job IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of jobids to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserJobAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserJobAccess ( string  user,
softint  id 
)
static

tests if the current user has access to the given single job ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe jobid to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserMapperAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserMapperAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of mapper IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of mapperids to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserMapperAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserMapperAccess ( string  user,
softint  id 
)
static

tests if the current user has access to the given single mapper ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe mapperid to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserPipelineAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserPipelineAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of data pipelines and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idsa list of pipelines to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserPipelineAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserPipelineAccess ( string  user,
string  name 
)
static

tests if the current user has access to the given single data pipeline and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
namethe pipeline to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserServiceAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserServiceAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of serviceids and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idsa list of serviceids to check
Exceptions
USER-ERRORthe user is not loaded
SERVICE-ACCESS-ERRORno authentication information supplied or user does not have access to the given services
Since
Qorus 5.1.20

◆ testUserServiceAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserServiceAccess ( string  user,
softint  id 
)
static

tests if the current user has access to the given single serviceid and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be

loaded or a USER-ERROR exception is thrown

Parameters
idthe serviceid to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserVmapAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserVmapAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idsa list of value map ids to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserVmapAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserVmapAccess ( string  user,
softint  id 
)
static

tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
idthe value map id to check
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserWorkflowAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserWorkflowAccess ( string  user,
list< auto >  ids 
)
static

tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of workflowids to check
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testUserWorkflowAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testUserWorkflowAccess ( string  user,
softint  id 
)
static

tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe workflowid to check
userthe user to check; if the user is provided by an external RBAC source, the user must already be loaded or a USER-ERROR exception is thrown
Exceptions
USER-ERRORthe user is not loaded
Since
Qorus 5.1.20

◆ testVmapAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testVmapAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of value map IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of value map ids to check

◆ testVmapAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testVmapAccess ( softint  id)
static

tests if the current user has access to the given single value map ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe value map id to check

◆ testWorkflowAccess() [1/2]

static bool OMQ::UserApi::Service::ServiceApi::testWorkflowAccess ( list< auto >  ids)
static

tests if the current user has access to the given list of workflow IDs and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idsa list of workflowids to check

◆ testWorkflowAccess() [2/2]

static bool OMQ::UserApi::Service::ServiceApi::testWorkflowAccess ( softint  id)
static

tests if the current user has access to the given single workflow ID and returns True (if authorization is granted) or False (if the user is not authorized)

Parameters
idthe workflowid to check

◆ tryGetResource()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryGetResource ( string  name,
hash< auto >  ctx,
int  code = 200,
*hash< auto >  hdr 
)
static

Returns the given text or binary file resource as its native type in the "body" key of a hash along with an HTTP response code and optionally HTTP headers; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned.

Example:
*hash<auto> h = ServiceApi::tryGetResource("image.jpg", cx);
Parameters
namethe name of the resource
ctxthe argument hash to the template code
codethe HTTP response code for the response, if not present then 200 "OK" is assumed
hdrany optional headers for the response (the "Content-Type" header is set from the templates "Content-Type" value automatically)
Returns
NOTHING if the resource does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template or file resource
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
See also

◆ tryGetResourceData()

static *data OMQ::UserApi::Service::ServiceApi::tryGetResourceData ( string  name,
*hash< auto >  ctx 
)
static

Returns the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned, if the given resource does not exist, then NOTHING is returned.

Example:
*binary img = UserApi::tryGetResourceData("image.jpg", cx);
Parameters
namethe name of the resource
ctxan optional argument hash to the template code
Returns
NOTHING if the file resource does not exist or the given text or binary file resource as its native type; if a template exists, then the template is rendered and returned
See also

◆ tryRenderTemplate()

static *hash<auto> OMQ::UserApi::Service::ServiceApi::tryRenderTemplate ( string  name,
hash< auto >  ctx 
)
static

render a template file resource and returns the rendered template if the template exists, otherwise returns NOTHING

Example:
*hash<auto> h = ServiceApi::tryRenderTemplate(name, ctx);
Parameters
namethe template file resource name
ctxthe argument hash to the template code
Returns
NOTHING if the template does not exist or a hash with the following keys:
  • code: the HTTP response code corresponding to the code argument
  • body: the rendered template
  • hdr: a hash of headers corresponding to the hdr argument plus the "Content-Type" key set from the template's "Content-Type" value)
See also

◆ uiExtensionRegister() [1/2]

static OMQ::UserApi::Service::ServiceApi::uiExtensionRegister ( OMQ::QorusExtensionHandler  handler)
static

registers the service as an extension of the system UI

Example:
ServiceApi::uiExtensionRegister(new MyExtensionHandler());
Parameters
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler

The registered extension will be available from:

  • default Qorus UI, "Extensions" section
  • directly in URL http(s)://<hostname>:<port>/UIExtension/<service type>-<service name>-<system resource id>

The system resource id value is assigned by Qorus itself, it is not predictable. Also it can vary accross various instalations. You can use uiExtensionRegister(handler, url_name) variant of this method to ensure usage of deterministic URL.

◆ uiExtensionRegister() [2/2]

static OMQ::UserApi::Service::ServiceApi::uiExtensionRegister ( OMQ::QorusExtensionHandler  handler,
string  url_name 
)
static

registers the service as an extension of the system UI with deterministic URL path

Example:
ServiceApi::uiExtensionRegister(new MyExtensionHandler(), "my_extension");
Parameters
handlerthe request handler for the requests to the extension, must be derived from OMQ::QorusExtensionHandler
url_namecustom name used in public URL

The registered extension will be available from:

  • default Qorus UI, "Extensions" section
  • directly in URL http(s)://<hostname>:<port>/UIExtension/<url_name>

◆ usleep() [1/2]

static int OMQ::UserApi::Service::ServiceApi::usleep ( date  arg)
static

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

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or sleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe amount of time in microseconds to sleep (1 microsecond = 1/1000000 of a second)
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ usleep() [2/2]

static int OMQ::UserApi::Service::ServiceApi::usleep ( softint  arg)
static

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

If the service is stopping, this method returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this method (or sleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters
argthe number of microseconds to sleep (1 microsecond = 1/1000000 of a second)
Returns
0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped
Exceptions
STOP-ERRORthe current object is stopping and this method already returned -1 as a warning
See also

◆ waitForEvents()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEvents ( softint  min_id = 1,
timeout  timeout_ms = 0 
)
static

return available system events

by default without any arguments will immediately return all available events in the cache

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
timeout_msoptional timeout waiting for events; if not present; the method returns immediately
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole

◆ waitForEventsAnd()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEventsAnd ( softint  min_id = 1,
auto  filter,
timeout  timeout_ms = 0,
auto  or_not 
)
static

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

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical and" comparisons to be applied to the events. If an event matches all of the criteria hashes in the first argument, then it is included in the resulting list. To match a criteria hash in the second argument with this API call, any of the criteria keys in a single hash can match, therefore, to get pure "logical and" behavior, the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the method returns immediately
or_notthis argument is an optional criteria list that can augment the list returned with negative matches. If this argument is present and any element in the system’s event list does not match any of the criteria hashes in the third argument, then it is also included in the returned event list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a single criteria hash to match, all of the criteria given as hash keys in the criteria hash must match, therefore, to get pure inverted "logical or" logic, the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-AND-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole

◆ waitForEventsOr()

static hash<auto> OMQ::UserApi::Service::ServiceApi::waitForEventsOr ( softint  min_id = 1,
auto  filter,
timeout  timeout_ms = 0,
auto  and_not 
)
static

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

Parameters
min_idthe minimum event ID to return; no event wil be returned that has an event ID less than this; the first event ID is always 1 (if min_id <= 1 then all events are returned that meet the given criteria)
filterthis argument is the criteria list for "logical or" comparisons to be applied to the events. If a system event matches any of the criteria hashes in the first argument, then it is included in the resulting list, subject to processing by the optional fourth argument. To match a criteria hash in the second argument with this API call, all of the criteria keys in each hash must match, therefore, to get pure "logical or" behavior the caller must specify only one hash key in each criteria hash; see Event Filter Criteria for a description of each criteria hash
timeout_msoptional timeout waiting for events; if not present or 0; the method returns immediately
and_notthis argument is an optional criteria list allowing the resulting event list to be filtered; if any event selected by the second argument matches all criteria hashes in the criteria hashes passed as the third argument, then it is filtered out of the resulting list. Note that the fourth argument, if present, is processed with inverted logic compared to the second argument; for a criteria hash to match, any of the criteria given as hash keys in a criteria hash can match, however, all criteria hashes must match for the filter to operate. Therefore, to get pure "logical and" filtering the caller must specify only one hash key per hash in the list making up the fourth argument; see Event Filter Criteria for a description of each criteria hash
Returns
a hash with the following keys:
  • lastid: the last event ID at the time the method returns
  • events: a list of event hashes (see eventhash for a detailed description); note that this key will be missing if no events are returned
  • shutdown: if this key is returned, it means the system is shutting down
Exceptions
GET-EVENTS-OR-ERRORempty or missing filter value
GET-EVENTS-ERRORnon-hash criteria element passed in event filter
INVALID-CRITERIA-CODEinvalid criteria code found in event filter
SHUTDOWN-ERRORthis exception is raised if any event API is called a second time after the "shutdown" key is returned
Note
It is not recommended to use this API in remote services, as high-volume message processing can have a negative impact on a Qorus cluster as a whole

Member Data Documentation

◆ ServiceCallContextKeys

const OMQ::UserApi::Service::ServiceApi::ServiceCallContextKeys = ("socket", "socket-info", "peer-info", "url", "id", "ssl", "user", "client-cert")

keys returned from the cx hash in getCallContext() if present

Since
Qorus 4.0.3

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