Qorus Integration Engine® Enterprise Edition 6.1.0_prod
Loading...
Searching...
No Matches
Qorus REST API v8

Table of Contents

Qorus REST API v8 Overview

Swagger Schema
A static version can be downloaded here: qorus-rest-api-v8.yaml; a dynamic version is available from every Qorus instance without authentication at URI paths /schema/qorus-rest-api-v8.yaml and /schema/qorus-rest-api-v8.json (ex: if Qorus is available on https://localhost:8011, then the dynamic schema can be retrieved from https://localhost:8011/schema/qorus-rest-api-v8.yaml and https://localhost:8011/schema/qorus-rest-api-v8.json).

/api/v8

This URI path implements v8 of the Qorus REST API

GET /api/v8

Description
Returns the top-level members of this version of the REST API

/api/v8/api/metrics

This REST URI path provides qorus metrics

GET /api/v8/api/metrics

Description
Returns qorus metrics
Return Value
This API returns a list of qorus metrics
  • TODO: the todo part

/api/v8/async-queues

This REST URI path provides actions and information about queues for asynchronous workflow steps

GET /api/v8/async-queues

Description
Returns informations about the asynchronous queues
Return Value
This API returns a list of hashes with the following keys:
  • queueid: the queue ID
  • name: the queue name
  • serviceid: optional: a related service id if present

POST /api/v8/async-queues

Description
Creates a new queue
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the queue
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the queue with markdown formatting
Return Value
This API returns a CreateQueueInfo hash with the following keys (a description of the new queue):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/async-queues?action=create

Description
Creates a new queue
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the queue
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the queue with markdown formatting
Return Value
This API returns a CreateQueueInfo hash with the following keys (a description of the new queue):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/async-queues/{queue}

This REST URI path provides actions and information about queues for asynchronous workflow steps

DELETE /api/v8/async-queues/{queue}

Description
Deletes the queue
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a QueueDeletionInfo hash with the following key (information about the queue that was deleted):
  • id (int): the ID of the queue that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such queue
Note
Requires one of the following permissions:

GET /api/v8/async-queues/{queue}

Description
Returns information about the current asynchronous queue
Return Value
This API returns a hash with the following keys:
  • queueid: the queue ID
  • name: the queue name
  • display_name: the queue's display name
  • short_desc: the queue's short description
  • description: the queue's description

PUT /api/v8/async-queues/{queue}

Description
Updates the current queue
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the queue; if not provided, the new name will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the queue
Return Value
This API returns an UpdateQueueInfo hash with the following keys (a description of the new queue):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/async-queues/{queue}?action=cancel

Description
cancels a queue entry with status OMQ::QS_Waiting setting OMQ::QS_Used.
Arguments
  • key the key to the entry in the given queue to cancel
Exceptions
UNKNOWN-QUEUEinvalid queue name
INVALID-KEYno entry exists in the given queue with the given key value
INVALID-STATUSqueue entry does not have status OMQ::QS_Waiting
WORKFLOW-ACCESS-ERRORthis is exeption is thrown when RBAC is enabled, and the call is made externally, and the user does not have the right to access the given workflow

POST /api/v8/async-queues/{queue}?action=clone

Description
Clones the current queue
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the queue; if not provided, the new name will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the queue
Return Value
This API returns a CloneQueueInfo hash with the following keys (a description of the new queue):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/async-queues/{queue}?action=file

Description
Returns the queue as a file that can be saved

GET /api/v8/async-queues/{queue}?action=info

Description
gets queue information for a queue entry from the queue name and key
Arguments
  • key the key to the entry
Return value
No value if no information is available, or a hash with the following keys:
  • workflow_instanceid: the workflow instance ID of the step and queue entry
  • stepid: the step ID of the step and queue entry
  • ind: the array index of the step and queue entry (0 for non-array steps)
  • queuekey: the queue key string
  • queue_data_status: the status of the queue entry: OMQ::QS_Waiting, OMQ::QS_Received, OMQ::QS_Used (Oracle only), or OMQ::QS_Error (rarely, in case of unparsable queue data)
  • corrected: if 1, then the queue entry has been corrected. meaning that the back-end function will not be executed and the step will automatically get a OMQ::StatComplete status.
  • data: the queue data, if any, set only when the queue data status is OMQ::QS_Received
Errors
  • 404 Not Found: the given key does not exist
  • 409 Conflict: UNKNOWN-QUEUE invalid queue name
  • 409 Conflict: WORKFLOW-ACCESS-ERROR this is exeption is thrown when RBAC is enabled, and the call is made externally, and the user does not have the right to access the given workflow

PUT /api/v8/async-queues/{queue}?action=key

Description
changes the key for a pending entry in a system queue, only when the status is OMQ::QS_Waiting (args: queue name, old key, new key)
Arguments
  • oldkey the old key name
  • newkey the new key name
Exceptions
UNKNOWN-QUEUEinvalid queue name
UPDATE-KEY-ERRORempty string passed for oldkey or newkey
QUEUE-KEY-UPDATE-ERRORno queue entry; queue entry does not have status OMQ::QS_Waiting
WORKFLOW-ACCESS-ERRORthis is exeption is thrown when RBAC is enabled, and the call is made externally, and the user does not have the right to access the given workflow

GET /api/v8/async-queues/{queue}?action=qinfo

Description
Returns a list of queue entries on a given queue from the queue ID and an optional status filter
Arguments
  • status: a single SQL status value; see OMQ::SQL_QS_ALL and OMQ::QS_ALL for valid values (takes both short and long status codes); default all statuses except "USED" are returned
  • user: the username to search for
  • user_interaction_locked: 1 or 0 for the user interaction locked status
  • limit: the maximum number of entries to return; default 100
  • offset: the offset to return; default 0
Return value
return either no value or a list of hashes having the following keys:
  • queuekey: (string) the key name
  • queue_data_status: (string) queue entry status:
  • workflow_instanceid: (int) the workflow instance ID of the queue record
  • stepid: (int) the step ID of the queue record
  • ind: (int) the step index of the queue record
  • user_interaction_locked: (bool) True if locked, False if not
  • user_interaction_user: (string) current user with owning the lock on the queue record, if set
  • user_interaction_modified: (date) the timestamp the user_interaction_user was last updated, if set
  • created: (date) created timestamp for the queue entry
  • modified: (date) modified timestamp for the queue entry
Exceptions
GET-QUEUE-INFO-ERRORqueueid is invalid
INVALID-STATUSstatus is invalid
Note
Queue entries with a "USED" status are only returned if the status argument is "USED" (OMQ::QS_Used) or "X" (OMQ::SQL_QS_Used)

GET /api/v8/async-queues/{queue}?action=status

Description
gives internal queue status (without parameters: for all queues)
Return Value
Hash with info. The top level key is the queue name, and the value is a queue summary hash.

The queue summary hash has the following structure. Key values are strings with the following format: "<workflow name>/<workflow version>" with queue status subkeys and with integer values corresponding to the number of workflows that have queue entries with the given statuses.

Exceptions
UNKNOWN-QUEUEinvalid queue name

POST /api/v8/async-queues/{queue}?action=update

Description
Updates a pending entry in a system queue with status WAITING and sets the status to RECEIVED. Data is stored serialized in YAML format so that type information is preserved when passed to the asynchronous step back end function
Arguments
This API takes the following hash arguments:
  • key (string): value of the key in the given queue
  • data (auto): data to post in the queue entry; this data will be passed to the back end function for evaluation
Return Value
This API returns a value of type string: "OK"
Errors
  • 400 Bad Request: invalid argument, invalid status in queue entry
  • 403 Forbidden: access or authorization error
  • 404 Not Found: unknown queue or queue key

GET /api/v8/classes

Description
Returns a list of hashes of all classes
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of class names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings with class names, versions, and IDs is returned
  • tags: optional; a hash of tags to match; only workflows matching at least one of the tags will be returned; use tag=value format as the value of this option
  • tag_case_insensitive: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons are made with case-insensitive comparisons
  • tag_partial_match: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons succeed if the value given as the tag value appears anywhere in the object's tag of the same name
Return Value
This API returns a list of hashes with the following keys (if neither list nor short options are passed as above):
  • classid: the class ID
  • name: the name of the class
  • version: the version of the class
  • description: the description of the class object
  • author: the author of the class object
  • created: the date/time the class object was created
  • modified: the date/time the class object was modified
  • source: the source file that the class object was created from
  • line: the offset in the source file for the source of the class object
  • edit_lock: the connection ID of the connection holding the edit lock, if any

POST /api/v8/classes

Description
Creates a new class
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the class
  • display_name (*string): the new display name for the class; generated from name if necessary
  • short_desc (*string): the short plain-text description for the class
  • desc (*string): the new description for the class with markdown formatting
  • version (string): the new version for the class
  • author (*string): the author of the class
  • source (string): the source code for the class
  • base_class_name (*string): the base class name for the class
  • language (*string): the programming language of the class
  • config_items (*list<UndefinedHash>): a list of config items for the class
  • requires (*list<string>): a list of classes required by this class
  • processor (*UndefinedHash): processor definitions
  • connectors (*UndefinedHash): connector definitions
  • class_name (*string): the class name for the class; must be a valid identifier
Return Value
This API returns a CreateClassInfo hash with the following keys (a description of the new class):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/classes?action=create

Description
Creates a new class
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the class
  • display_name (*string): the new display name for the class; generated from name if necessary
  • short_desc (*string): the short plain-text description for the class
  • desc (*string): the new description for the class with markdown formatting
  • version (string): the new version for the class
  • author (*string): the author of the class
  • source (string): the source code for the class
  • base_class_name (*string): the base class name for the class
  • language (*string): the programming language of the class
  • config_items (*list<UndefinedHash>): a list of config items for the class
  • requires (*list<string>): a list of classes required by this class
  • processor (*UndefinedHash): processor definitions
  • connectors (*UndefinedHash): connector definitions
  • class_name (*string): the class name for the class; must be a valid identifier
Return Value
This API returns a CreateClassInfo hash with the following keys (a description of the new class):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/classes?action=list

Description
Identical to GET /api/classes
See also
GET /api/classes

/api/v8/classes/{id_or_name}

This REST API path provides actions and information about specific class objects

DELETE /api/v8/classes/{id_or_name}

Description
Deletes the class
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a ClassDeletionInfo hash with the following key (information about the class that was deleted):
  • id (int): the ID of the class that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such function
Note
Requires one of the following permissions:

GET /api/v8/classes/{id_or_name}

Description
Returns a hash of information about the current class object
Return Value
This API returns a hash with the following keys:
  • name: the name of the class object
  • version: the version of the class object
  • classid: the class object ID
  • description: the description of the class
  • author: the author of the class
  • body: the source code for the class object
  • created: the date/time the class was created
  • modified: the date/time the class was modified
  • createdby: (deprecated) always "omq"
  • modifiedby: (deprecated) always "omq"
  • tags: any user-defined tags on the class object
  • source: the source file that the class object was created from
  • offset: the offset in the source file for the source of the class object
  • host: the hostname of the machine where the class object was loaded from
  • user: the OS user who loaded the class object
  • [edit_lock]: the connection ID of the WebSocket connection holding the edit lock

PUT /api/v8/classes/{id_or_name}

Description
Updates the current class
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the class
  • display_name (*string): the new display name for the class; generated from name if necessary
  • short_desc (*string): the short plain-text description for the class
  • desc (*string): the new description for the class with markdown formatting
  • version (*string): the new version for the class
  • author (*string): the author of the class
  • source (*string): the source code for the class
  • base_class_name (*string): the base class name for the class
  • language (*string): the programming language of the class
  • config_items (*list<UndefinedHash>): a list of config items for the class
  • requires (*list<string>): a list of classes required by this class
  • processor (*UndefinedHash): processor definitions
  • connectors (*UndefinedHash): connector definitions
  • class_name (*string): the class name for the class; must be a valid identifier
Return Value
This API returns an UpdateClassInfo hash with the following keys (a description of the new class):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/classes/{id_or_name}?action=clone

Description
Clones the current class; all parameters are optional and override the cloned class's values. If no version is provided, then the current version is incremented in the cloned class; if a version but no name is provided, then a new name is generated for the cloned class
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the class
  • display_name (*string): the new display name for the class; generated from name if necessary
  • short_desc (*string): the short plain-text description for the class
  • desc (*string): the new description for the class with markdown formatting
  • version (*string): the new version for the class
  • author (*string): the author of the class
  • source (*string): the source code for the class
  • base_class_name (*string): the base class name for the class
  • language (*string): the programming language of the class
  • config_items (*list<UndefinedHash>): a list of config items for the class
  • requires (*list<string>): a list of classes required by this class
  • processor (*UndefinedHash): processor definitions
  • connectors (*UndefinedHash): connector definitions
  • class_name (*string): the class name for the class; must be a valid identifier
Return Value
This API returns a CloneClassInfo hash with the following keys (a description of the new class):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/classes/{id_or_name}?action=file

Description
Returns the class as a file that can be saved

/api/v8/command

This URI path provides API support for Qorus remote code deployments

POST /api/v8/command

Description
Returns the result of the command
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • args: (optional) command-line arguments
  • cmd: (required) the command to execute (ex: oload); if the user does not have the REMOTE-EXEC-ALL permission, this argument must be one of the following values:
    • make-release
    • ocmd
    • ojview
    • oload
    • oprop
    • ostart
    • ostatus
    • ostop
    • oview
    • qdp
    • qrest
    • saprest
    • schema-reverse
    • schema-tool
    • sfrest
    • soaputil
    • sqlutil
  • dir: (required for make-release and oload)
oload Arguments
  • files: (required) a list of files for the oload command
Errors
  • 400 Bad Request: missing or invalid option
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 500 Internal Server Error: returned if there is an error executing the command
Note

/api/v8/connections

This REST URI path provides actions and information about remote Qorus, user and datasource connections

GET /api/v8/connections

Description
Returns a list of hash information for all Qorus connections
Arguments
This API takes the following hash argument:
  • with_password (*bool): include the password in the "url" and "url_hash" keys
Return Value
This API returns a value of type list<ConnectionInfo>: information about the connection

POST /api/v8/connections

Description
Creates a new connection from the arguments; permissions required depend on the URL
Arguments
This API takes the following hash arguments:
  • name (*string): the internal name of the connection
  • display_name (*string): the display name of the connection
  • short_desc (*string): the plain-text short description for the new connection
  • desc (*string): the description for the new connection with markdown formatting
  • url (string): the connection string for the new connection
Return Value
This API returns a NewConnectionInfo hash with the following keys (information about the connection created):
  • id (int): the new connection ID
  • name (string): the name of the new connection
  • display_name (string): the display name of the new connection
  • short_desc (string): the connection's description in plain text
  • desc (string): the connection's description with markdown formatting
  • info (string): a string describing the operation performed
  • action (string): the action performed
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error

POST /api/v8/connections?action=create

Description
Creates a new connection from the arguments
Arguments
This API takes the following hash arguments:
  • name (*string): the internal name of the connection
  • display_name (*string): the display name of the connection
  • short_desc (*string): the plain-text short description for the new connection
  • desc (*string): the description for the new connection with markdown formatting
  • url (string): the connection string for the new connection
  • tags (*UndefinedHash): key-value pairs for the new connection
Return Value
This API returns a NewConnectionInfo hash with the following keys (information about the connection created):
  • id (int): the new connection ID
  • name (string): the name of the new connection
  • display_name (string): the display name of the new connection
  • short_desc (string): the connection's description in plain text
  • desc (string): the connection's description with markdown formatting
  • info (string): a string describing the operation performed
  • action (string): the action performed
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/connections/{name}

This REST URI path provides actions and information related to a specific connection, which may be:

DELETE /api/v8/connections/{name}

Description
Permanently deletes the current user connection, datasource, or remote Qorus connection
Arguments
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error

GET /api/v8/connections/{name}

Description
Returns a hash information for the current user connection, datasource, or remote Qorus connection
Arguments
This API takes the following hash argument:
  • with_password (*bool): include the password in the "url" and "url_hash" keys
Return Value
This API returns a ConnectionInfo hash with the following keys (information about the connection):
  • connectionid (int): the unique connection ID
  • name (string): the name of the connection
  • display_name (string): the display name of the connection
  • conntype (string): either "DATASOURCE", "REMOTE", or "USER-CONNECTION"
  • short_desc (string): the short plain-text description of the connection
  • description (string): a description of the connection
  • url (string): the URL to the remote host
  • monitor (bool): a boolean indicating if the connection is monitored or not
  • last_check (*date): the date/time value the connection was last checked (loopback remote connections are not checked)
  • updated (*date): the date/time the connection was last updated
  • status (string): \ "OK", "not checked", or an error message
  • up (bool): a boolean indicating if the connection was monitored to be up or not
  • loopback (*bool): (only for remote connections) indicates if the connection is a loopback connection
  • type (string): the connection type ("datasource", "rest", "soap", etc)
  • url_hash (UndefinedHash): a hash of broken-down URL components
  • enabled (bool): indicates if the connecton is enabled or not
  • locked (*bool): indicates if the connection can be edited or not (only the system schema connection is locked and cannot be edited)
  • debug_data (*bool): if data debugging is enabled for the connection
  • tags (*UndefinedHash): any tags for the connection
  • has_provider (bool): if the connection supports a data provider
  • children_can_support_apis (bool): if the data provider or any children support APIs
  • children_can_support_records (bool): if the data provider or any children support records
  • children_can_support_observers (bool): if the data provider or any children support event observation
  • children_can_support_messages (bool): if the data provider or any children support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • opts (*UndefinedHash): a hash of options for the connection
  • features (*QorusBooleanSetInfo): a list of connection-specific features supported by the connection
    • key (bool): bool value
  • dataprovider_subtypes (*UndefinedHashOfHashes): a hash of data provider subtype option info; top-level keys are data provider subtypes supported by the connection, values are option hashes
    • key (UndefinedHash): UndefinedHash value
  • auth_request_uri (*string): a URI to make OAuth2 authorization code grant requests, if supported by the connection
  • coord-mode (*bool): if coordinated mode is enabled (datasources only)
  • safe_url (*string): a URL string without any password information
  • shared-pool (*string): summary information about the DatasourcePool object backing a datasource connection
  • warning-timeout (*int): datasource warning timeout in milliseconds
  • error-timeout (*int): datasources error timeout in milliseconds
  • pool-wait-max (*int): (datasources only) the maximum wait time for a pool connection to become available in milliseconds
  • pool-reqs (*int): (datasources only) the number of connection requests on the pool
  • pool-hits (*int): (datasources only) the number of connection requests that could be served immediately without blocking
  • pool-miss (*int): (datasources only) the number of connection requests that could be served only after blocking
  • pool-hit-pct (*float): the percentage of hits to misses
  • deps (*list<ConnectionDependencyInfo>): a list of dependent interfaces
  • alerts (*list<AlertInfo>): a list of alerts raised against the connection
  • health (*string): (remote Qorus connections only) a string giving the health color code of the instance
  • instance-key (*string): (remote Qorus connections only) the Qorus instance key of the remote instance
  • omq-version (*string): (remote Qorus connections only) the Qorus version
  • alert-summary (*SystemAlertInfo): summary of alert info
  • error (*string): (remote Qorus connections only) any error summary string for the remote instance
  • created (date): the created date of the connection
  • modified (date): the last modified date of the connection
  • needs_auth (*bool): True if the connection requires OAuth2 authorization

PUT /api/v8/connections/{name}

Description
Modifies the current user connection, datasource, or remote Qorus connection
Arguments
This API takes the following hash arguments:
  • name (*string): the new name of the connection
  • display_name (*string): the new display name of the connection
  • short_desc (*string): a new short description for the connection
  • desc (*string): a new description for the connection
  • url (*string): a new URL for the connection
  • options (*UndefinedHash): new options for the connection
  • tags (*UndefinedHash): new tags for the connection
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: error executing the change

POST /api/v8/connections/{name}?action=clone

Description
Clones the current connection; all parameters are optional and override the cloned connection's values. If no name is provided, then a new name is generated for the cloned connection
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the connection
  • display_name (*string): the new display name for the connection; generated from name if necessary
  • short_desc (*string): the short plain-text description for the connection
  • desc (*string): the new description for the connection with markdown formatting
Return Value
This API returns a CloneConnectionInfo hash with the following keys (a description of the new connection):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/connections/{name}?action=disable

Description
Disables the current user connection, datasource, or remote Qorus connection if it is enabled; if the connection is already disabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error

PUT /api/v8/connections/{name}?action=disableDebugData

Description
Disables data debugging for a user connection (and only for user connections)
Arguments
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/connections/{name}?action=enable

Description
Enables the current user connection, datasource, or remote Qorus connection if it is disabled; if the connection is already enabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error

PUT /api/v8/connections/{name}?action=enableDebugData

Description
Enables data debugging for a user connection (and only for user connections)
Arguments
Return Value
This API returns a ConnectionUpdateResultInfo hash with the following keys (information about the result of the operation):
  • info (string): a string providing information about the connection update action
  • changes (*UndefinedHash): list of attributes changed on the connection
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/connections/{name}?action=file

Description
Returns the connection as a file that can be saved

PUT /api/v8/connections/{name}?action=ping

Description
Checks connectivity to the current user connection, datasource, or remote Qorus connection; if the connection was up and is monitored to be down, then any dependent interfaces will be disabled. If the connection was down and is monitored to be up, then any eligible interfaces will be reenabled.
Arguments
Return Value
This API returns a PingResultInfo hash with the following keys (the result of the ping operation):
  • ok (bool): the status of the ping
  • name (string): the name of the connection
  • desc (string): the description of the connection
  • url (string): the URL for the connection
  • opts (UndefinedHash): a hash of options for the connection (if any)
  • time (date): the elapsed time for the ping
  • info (string): "OK" if the ping was successful or an error message if not
  • result (string): a string representation of the time in seconds (ex: "0.25s")
  • ping_flags (int): ping flags as per Ping Flags
  • ping_info (*UndefinedHash): a hash of optional additional info about the ping operation
  • ex (*UndefinedHash): any exception hash will be stored here in case of a ping failure

/api/v8/connections/{name}/provider

This URI path provides access to a data provider created from a Qorus connection

DELETE /api/v8/connections/{name}/provider

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/connections/{name}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/connections/{name}/provider?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/connections/{name}/provider?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

PUT /api/v8/connections/{name}/provider?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/connections/{name}/provider?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/connections/{name}/provider?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/connections/{name}/provider?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/connections/{name}/provider?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/connections/{name}/provider?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/connections/{name}/provider?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/connections/{name}/provider?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/connections/{name}/provider?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/connections/{name}/provider/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/connections/{name}/provider/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/connections/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/connections/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/constants

This REST API path provides actions and information about Qorus constant objects

GET /api/v8/constants

Description
Returns a list of hashes of all constant objects
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of hashes with the following keys (if neither list nor short options are passed as above):
  • constantid: the constant ID
  • name: the name of the constant
  • version: the version of the constant
  • description: the description of the constant object
  • author: the author of the constant object
  • created: the date/time the constant object was created
  • modified: the date/time the constant object was modified
  • source: the source file that the constant object was created from
  • line: the offset in the source file for source of the constant object

POST /api/v8/constants

Description
Creates a new constant
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the constant
  • desc (*string): the new description for the constant with markdown formatting
  • version (string): the new version for the constant
  • author (*string): the author of the constant
  • source (string): the source code for the constant
Return Value
This API returns a CreateConstantInfo hash with the following keys (a description of the new constant):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/constants?action=create

Description
Creates a new constant
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the constant
  • desc (*string): the new description for the constant with markdown formatting
  • version (string): the new version for the constant
  • author (*string): the author of the constant
  • source (string): the source code for the constant
Return Value
This API returns a CreateConstantInfo hash with the following keys (a description of the new constant):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/constants/{id_or_name}

This REST API path provides actions and information about specific constant objects

DELETE /api/v8/constants/{id_or_name}

Description
Deletes the constant
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a ConstantDeletionInfo hash with the following key (information about the constant that was deleted):
  • id (int): the ID of the constant that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such constant
Note
Requires one of the following permissions:

GET /api/v8/constants/{id_or_name}

Description
Returns a hash of information about the current constant object
Return Value
This API returns a hash with the following keys:
  • name: the name of the constant object
  • version: the version of the constant object
  • constantid: the constant object ID
  • description: the description of the constant object
  • author: the author of the constant object
  • body: the source code for the class object
  • created: the date/time the constant object was created
  • modified: the date/time the constant object was modified
  • createdby: (deprecated) always "omq"
  • modifiedby: (deprecated) always "omq"
  • tags: any user-defined tags on the constant object
  • source: the source file that the constant object was created from
  • offset: the offset in the source file for the source of constant object
  • host: the hostname of the machine where the constant object was loaded from
  • user: the OS user who loaded the constant object

PUT /api/v8/constants/{id_or_name}

Description
Updates the current constant
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the constant
  • desc (*string): the new description for the constant with markdown formatting
  • version (*string): the new version for the constant
  • author (*string): the author of the constant
  • source (*string): the source code for the constant
  • constant_type (*string): The type of the constant
Return Value
This API returns an UpdateConstantInfo hash with the following keys (a description of the new constant):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/constants/{id_or_name}?action=clone

Description
Clones the current constant; all parameters are optional and override the cloned constant's values. If no version is provided, then the current version is incremented in the cloned constant; if a version but no name is provided, then a new name is generated for the cloned constant
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the constant
  • desc (*string): the new description for the constant with markdown formatting
  • version (*string): the new version for the constant
  • author (*string): the author of the constant
  • source (*string): the source code for the constant
Return Value
This API returns a CloneConstantInfo hash with the following keys (a description of the new constant):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/constants/{id_or_name}?action=file

Description
Returns the constant as a file that can be saved

/api/v8/creator

This REST URI path provides actions and information for the base path of the creator API

GET /api/v8/creator?action=locks

Description
Returns a list of lock and reservation information for debugging

/api/v8/creator/class

This REST URI path provides actions and information for classes in the creator API

GET /api/v8/creator/class

Description
Returns information about class metadata

PUT /api/v8/creator/class?action=new

Description
Reserves a class id for creation and returns metadata information for classes
Return Value
This API returns a hash with the following keys:
  • type: (string) class
  • id: (int) the class ID reserved
  • fields: (hash) field description for a new class
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_CREATE

/api/v8/creator/class/{class}

This REST URI path provides actions and information for a specific class in the creator API

GET /api/v8/creator/class/{class}

Description
Returns information for a specific class with field information as well

PUT /api/v8/creator/class/{class}?action=editLock

Description
Locks a class for editing in the UI
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

PUT /api/v8/creator/class/{class}?action=releaseEditLock

Description
Releases an edit lock on a class
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

/api/v8/creator/config-item

This REST URI path provides actions and information for config items in the creator API

/api/v8/creator/connection

This REST URI path provides actions and information for connections in the creator API

GET /api/v8/creator/connection

Description
Returns a list of all remote connections (remote connections under "qorus", user connections under "user", and datasource connections under "datasources")
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
Returns a list of hashes; the "conntype" value determines the hash format as follows:
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/creator/connection/{connection}

This REST URI path provides actions and information for a specific connection in the creator API

GET /api/v8/creator/connection/{connection}

Description
Returns information for a specific connection with field information as well

PUT /api/v8/creator/connection/{connection}?action=editLock

Description
Locks a connection for editing in the UI
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique WebSocket connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

PUT /api/v8/creator/connection/{connection}?action=releaseEditLock

Description
Releases an edit lock on a connection
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

/api/v8/creator/job

This REST URI path provides actions and information for jobs in the creator API

GET /api/v8/creator/job

Description
Returns information about job metadata

PUT /api/v8/creator/job?action=new

Description
Reserves a job id for creation and returns metadata information for jobs
Return Value
This API returns a hash with the following keys:
  • type: (string) job
  • id: (int) the job ID reserved
  • fields: (hash) field description for a new job
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_CREATE

/api/v8/creator/job/{job}

This REST URI path provides actions and information for a specific job in the creator API

GET /api/v8/creator/job/{job}

Description
Returns information for a specific job with field information as well

PUT /api/v8/creator/job/{job}?action=editLock

Description
Locks a job for editing in the UI
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

PUT /api/v8/creator/job/{job}?action=releaseEditLock

Description
Releases an edit lock on a job
Arguments
This API takes the following hash arguments (in the message body):
  • cid: (int) the unique connection ID
  • tab_token: (string) the unique connection ID for the tab subchannel
Return Value
This API returns a hash with the following keys:
  • locked: (bool) True or False
  • info: (hash) only included if the lock fails
    • intent: warning
    • content: msg explaining that the object is already locked
Errors
  • 400 Bad Request: returned if the request has invalid arguments
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_UPDATE

/api/v8/creator/service

This REST URI path provides actions and information for services in the creator API

GET /api/v8/creator/service

Description
Returns information about service metadata

PUT /api/v8/creator/service?action=new

Description
Reserves a service id for creation and returns metadata information for services
Return Value
This API returns a hash with the following keys:
  • type: (string) service
  • id: (int) the service ID reserved
  • fields: (hash) field description for a new service
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_CREATOR_CONTROL or OMQ::QR_CREATOR_CREATE

/api/v8/creator/service/{service}

This REST URI path provides actions and information for a specific service in the creator API

GET /api/v8/creator/service/{service}

Description
Returns information for a specific service with field information as well

/api/v8/dataprovider

This URI path provides access to data provider functionality

GET /api/v8/dataprovider

Returns a list of child URLs for this class

POST /api/v8/dataprovider?action=callApi

Description
Makes an API call with a request-response data provider and returns the response
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • args (auto): any arguments to the API call; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve arguments
  • request_options (*UndefinedHash): any request options
Return Value
This API returns a value of type auto: the return value of the API call
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=callApiFromUi

Description
Makes an API call with a request-response data provider and returns the response; certain arguments are expected in a format used by UI clients
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • args (auto): any arguments to the API call; if this argument is a hash, then each hash key must be assigned a hash value with type and value keys, additionally, if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve arguments
  • request_options (*UndefinedUiHash): any request options
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
Return Value
This API returns a value of type auto: the return value of the API call
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

PUT /api/v8/dataprovider?action=compareManyTypes

Description
Takes a list of hashes in types giving type and base_type information to compare and returns a list of the results of each comparison.
Arguments
This API takes the following hash argument:
  • types (QorusTypeComparisonSetInfo): a hash of hashes keyed by a unique user-defined comparison identifier
    • base_type (QorusTypeInfo): hash describing the input or receiving type (type of variable to accept type)
      • type (string): one of connection, datasource, factory, remote, or type
      • name (string): the name of the type, connection, factory, etc
      • path (*string): the path to the final object
      • subtype (*string): the subtype for type = connection
      • options (*hash<auto>): create option for type = factory
      • hasApiContext (*bool): True if the type is a factory with options to be handled in an API
    • type (QorusTypeInfo): a hash describing the output or sending type (type of value to be assigned to base_type)
      • type (string): one of connection, datasource, factory, remote, or type
      • name (string): the name of the type, connection, factory, etc
      • path (*string): the path to the final object
      • subtype (*string): the subtype for type = connection
      • options (*hash<auto>): create option for type = factory
      • hasApiContext (*bool): True if the type is a factory with options to be handled in an API
Return Value
This API returns a QorusBooleanSetInfo hash; keys have the following format:
  • any (bool): Returns a hash keyed by hash keys in the types argument where the values are boolean values of the results of the type comparisons
Errors
  • 400 Bad Request: missing or invalid types argument; non-unique name in types list
  • 404 Not Found: the given type, factory, connection, etc cannot be found

PUT /api/v8/dataprovider?action=compareTypes

Description
Compares two types for assignment compatibility; takes a base_type and a type argument and returns
Arguments
This API takes the following hash arguments:
  • base_type (QorusTypeInfo): hash describing the input or receiving type (type of variable to accept type)
    • type (string): one of connection, datasource, factory, remote, or type
    • name (string): the name of the type, connection, factory, etc
    • path (*string): the path to the final object
    • subtype (*string): the subtype for type = connection
    • options (*hash<auto>): create option for type = factory
    • hasApiContext (*bool): True if the type is a factory with options to be handled in an API
  • type (QorusTypeInfo): a hash describing the output or sending type (type of value to be assigned to base_type)
    • type (string): one of connection, datasource, factory, remote, or type
    • name (string): the name of the type, connection, factory, etc
    • path (*string): the path to the final object
    • subtype (*string): the subtype for type = connection
    • options (*hash<auto>): create option for type = factory
    • hasApiContext (*bool): True if the type is a factory with options to be handled in an API
Return Value
This API returns a value of type bool: True if type can be assigned to base_type, False if not
Errors
  • 400 Bad Request: missing or invalid types argument; non-unique name in types list
  • 404 Not Found: the given type, factory, connection, etc cannot be found

POST /api/v8/dataprovider?action=createRecords

Description
Creates new records in a data provider and returns the number of created records
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • records (list<UndefinedHash>): the list of new records; each hash in the list represents a new record and must have keys that correspond to valid field names, values are subjected to template resolution by calls to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
Return Value
This API returns a value of type list<UndefinedHash>: the record set inserted
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=createRecordsFromUi

Description
Creates new records in a data provider and returns the number of created records
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • records (list<UndefinedUiHash>): the list of new records; each hash in the list represents a new record and must have keys that correspond to valid field names, values are subjected to template resolution by calls to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
Return Value
This API returns a value of type list<UndefinedHash>: the record set inserted
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=deleteRecords

Description
Deletes records from a data provider and returns the number of deleted records
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • where (*UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column with op and value keys; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedHash): any search options
Return Value
This API returns an AffectedRecordInfo hash with the following key (a hash describing the number of records affected by the operation):
  • affected_records (int): the number of records affected by the operation
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=deleteRecordsFromUi

Description
Deletes records from a data provider and returns the number of deleted records
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • where (*UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column with op and value keys; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedUiHash): any search options
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
Return Value
This API returns an AffectedRecordInfo hash with the following key (a hash describing the number of records affected by the operation):
  • affected_records (int): the number of records affected by the operation
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=searchRecords

Description
Performs a search in a record-based data provider and returns the result as a list of zero or more hashes representing the records matched
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • where (*UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column with op and value keys; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedHash): any search options
Return Value
This API returns a value of type *list<UndefinedHash>: the records matching the search criteria
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=searchRecordsFromUi

Description
Performs a search in a record-based data provider and returns the result as a list of zero or more hashes representing the records matched; certain arguments are expected in a format used by UI clients
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • where (*UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column with op and value keys; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedUiHash): any search options
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
Return Value
This API returns a value of type *list<UndefinedHash>: the records matching the search criteria
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=searchSingleRecord

Description
Performs a search in a record-based data provider and returns the result record, if there is a match, or no value if not
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • where (UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedHash): any search options
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
  • any (auto): the record matching the search criteria or no value if there is no match
Errors
  • 400 Bad Request: missing or invalid required arguments or if multiple records match the search criteria
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=searchSingleRecordFromUi

Description
Performs a search in a record-based data provider and returns the result record, if there is a match, or no value if not; certain arguments are expected in a format used by UI clients
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • where (UndefinedUiHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
    • key (UndefinedHash): UndefinedHash value
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedUiHash): any search options
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
  • any (auto): the record matching the search criteria or no value if there is no match
Errors
  • 400 Bad Request: missing or invalid required arguments or if multiple records match the search criteria
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=sendMessage

Description
Sends a message with a message-based data provider
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • message_id (string): the ID of the message to send; must be a message supported by the data provider
  • message (auto): the message body; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve arguments
  • message_options (*UndefinedHash): any message options
Return Value
This API returns a value of type string: the string OK
Errors
  • 400 Bad Request: missing or invalid message ID or message body
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=sendMessageFromUi

Description
Sends a message with a message-based data provider; certain arguments are expected in a format used by UI clients
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • message_id (string): the ID of the message to send; must be a message supported by the data provider
  • message (auto): the message body; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve arguments
  • message_options (*UndefinedHash): any message options
Return Value
This API returns a value of type string: the string OK
Errors
  • 400 Bad Request: missing or invalid message ID or message body
Note
Requires one of the following permissions:

PUT /api/v8/dataprovider?action=type

Description
Returns type information for the given data provider information
Arguments
This API takes the following hash arguments:
  • soft (*bool): if a "soft" type should be returned
  • type (QorusTypeInfo): hash describing the input or receiving type (type of variable to accept type)
    • type (string): one of connection, datasource, factory, remote, or type
    • name (string): the name of the type, connection, factory, etc
    • path (*string): the path to the final object
    • subtype (*string): the subtype for type = connection
    • options (*hash<auto>): create option for type = factory
    • hasApiContext (*bool): True if the type is a factory with options to be handled in an API
Return Value
This API returns a DataProviderTypeInfo hash with the following keys (data provider type information):
  • name (string): the type name
  • display_name (*string): the type's display name
  • short_desc (*string): the short, plain-text description of the type
  • desc (string): the description of the type
  • supported_options (*UndefinedHash): transformation options supported by the type
  • options (*UndefinedHash): transformation option values
  • base_type (string): the Qore base type name
  • mandatory (bool): can be null / missing?
  • default_value (auto): any default value for the type
  • types_accepted (list<string>): list of types accepted on input
  • types_returned (list<string>): list of types returned
  • fields (*UndefinedHash): fields supported by the type
  • can_manage_fields (bool): True if fields can be added dynamically to the type
  • tags (*UndefinedHash): any tags set on the type
  • or_nothing_type (bool): if True, the type will accept NOTHING

POST /api/v8/dataprovider?action=updateRecords

Description
Performs an update action in a data provider and returns the number of records updated
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedHash): factory constructor options; invalid options are silently ignored
  • set (UndefinedHash): keys are field names and values are field values to be updated; values will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • where (*UndefinedHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column with op and value keys; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedHash): any search options
Return Value
This API returns an AffectedRecordInfo hash with the following key (a hash describing the number of records affected by the operation):
  • affected_records (int): the number of records affected by the operation
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

POST /api/v8/dataprovider?action=updateRecordsFromUi

Description
Performs an update action in a data provider and returns the number of records updated
Arguments
This API takes the following hash arguments:
  • type (string): the type of path: factory, connection, datasource, or remote
  • name (string): the initial segment of the data provider path
  • path (*string): the path to the data provider
  • options (*UndefinedUiHash): factory constructor options; invalid options are silently ignored
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
  • set (UndefinedUiHash): keys are field names and values are field values to be updated; values will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
    • key (UndefinedHash): UndefinedHash value
  • where (UndefinedUiHash): the search criteria for the search where keys are field names and values are either values to be matched or a hash describing a comparison operator for the column; if present this will be resolved as a template with a call to UserApi::expandTemplatedValue() with context as the local context
    • key (UndefinedHash): UndefinedHash value
  • context (*UndefinedHash): any context data to be used to resolve the where argument
  • search_options (*UndefinedUiHash): any search options
    • type (string): the expected type of the argument
    • value (auto): the value of the argument, for values that cannot be serialized as JSON, this will be a string in YAML format
Return Value
This API returns an AffectedRecordInfo hash with the following key (a hash describing the number of records affected by the operation):
  • affected_records (int): the number of records affected by the operation
Errors
  • 400 Bad Request: missing or invalid required arguments
Note
Requires one of the following permissions:

/api/v8/dataprovider/actions

This URI path provides access to data provider action functionality

GET /api/v8/dataprovider/actions

Description
Returns matching DataProvider actions
Arguments
This API takes the following hash arguments:
  • app (*string): search for actions associated with the given app
  • search (*string): a substring or regular expression search value to look for in the actions description and short description fields
  • search_regex (*bool): if True then any search value will be assumed to be a regular expression instead of a substring
Return Value
This API returns a value of type *list<DataProviderActionInfo>: list of DataProvider actions

/api/v8/dataprovider/apps

This URI path provides access to data provider application functionality

GET /api/v8/dataprovider/apps

Description
Returns matching DataProvider applications
Arguments
This API takes the following hash arguments:
  • search (*string): a substring or regular expression search value to look for in the application name and description fields
  • search_regex (*bool): if True then any search value will be assumed to be a regular expression instead of a substring
Return Value
This API returns a value of type *list<DataProviderAppInfo>: list of DataProvider applications

GET /api/v8/dataprovider/apps?action=clientInfo

Description
Retrieves info about the OAuth2 client cache
Arguments
This API takes no arguments
Return Value
This API returns an OAuth2ClientCacheInfo hash with the following keys (information about the OAuth2 client cache):
  • count (int): number of clients cached
  • timestamp (date): the date the cache was refreshed

POST /api/v8/dataprovider/apps?action=refreshClients

Description
Refresh OAuth2 client information from Qore Technologies' cloud server
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/dataprovider/apps/{app}

This URI path provides access to data provider application functionality

GET /api/v8/dataprovider/apps/{app}

Description
Returns info about the current DataProvider application
Arguments
Return Value
This API returns a DataProviderAppInfo hash with the following keys (info about the current DataProvider application):
  • name (string): the unique application name
  • display_name (string): the dispay name for the application
  • short_desc (string): the application's short description in plain text
  • desc (string): the application description with markdown formatting
  • builtin (bool): if the application is builtin to Qorus or not
  • scheme (*string): any scheme identifying a connection for the application
  • logo (string): a link to the logo data that will be served directly
  • logo_file_name (string): the file name of the logo
  • logo_mime_type (string): the mime type for logo
  • oauth2_clients (*list<OAuth2AppClientInfo>): OAuth2 client info, if any
  • connections (*list<string>): a list of existing connections with the given scheme
  • actions (*list<DataProviderActionInfo>): list of all actions on each application
  • oauth2_client (*OAuth2ClientInfo): OAuth2 client info, if any
    • oauth2_client_id (string): the OAuth2 client ID to use
    • oauth2_client_secret (string): the OAuth2 client secret to use
    • url_type (string): auto: automatically generated or required: the user must provide a URL
    • oauth2_auth_url (*string): if set, this overrides the REST connection option
    • oauth2_token_url (*string): if set, this overrides the REST connection option
    • required_options (*list<string>): a list of connection options that must be filled in by the user to create the connection

POST /api/v8/dataprovider/apps/{app}?action=createConnection

Description
Creates a new connection for the application
Arguments
This API takes the following hash arguments:
  • options (*UndefinedHash): options and values to use
  • tags (*UndefinedHash): any tags to add on the connection
Return Value
This API returns a ConnectionCreationInfo hash with the following keys (connection creation info):
  • name (string): the new connection name
  • desc (string): the new connection description
  • id (int): the new connection ID
  • display_name (string): the display name for the connection
  • short_desc (string): the short description for the connection
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/dataprovider/apps/{app}?action=getCreateConnectionOptions

Description
Returns info about options required to create a new connection for the current action
Arguments
This API takes the following hash argument:
  • options (*UndefinedHash): options and values to use
Return Value
This API returns a ConnectionOptionSet hash with the following keys (connection option info; keys are option names):
  • type (string): data type of the option
  • display_name (string): the display name of the option
  • short_desc (string): short description of the option in plain text
  • desc (string): description of the option with markdown formatting
  • required (*bool): is the option required?
  • required_groups (*list<string>): any groups of required options that this option is a member of
  • arg_schema (*UndefinedHash): description of any subfields required for this option
  • default_value (auto): any default value for the option
  • default_value_desc (*string): the description for the default value
  • readonly (*bool): if the option is read only
  • sensitive (*bool): is the value sensitive?
  • multiselect (*bool): are allowed values the allowed values for a list type?
  • allowed_values (*list<AllowedValueInfo>): allowed values for the option
  • allowed_values_creatable (*bool): can the value be a value not in allowed_values?
  • example_value (*string): an example value for the option
  • subst_env_vars (bool): will environment variables in string values be substituted?
  • freeform (bool): modifier for the file-as-string type: can a freeform location option be returned?
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/dataprovider/apps/{app}?action=logo

Return Value
Returns the application's logo with the Content-Type as the logo's MIME type

PUT /api/v8/dataprovider/apps/{app}?action=updateConnection

Description
Updates an existing connection for the application
Arguments
This API takes the following hash argument:
  • options (*UndefinedHash): attributes to update on the connection; at least either the id or name attributes must be present to identify the connection; if id is present, then name can be used to rename the connection
Return Value
This API returns a ConnectionUpdateInfo hash with the following keys (connection creation info):
  • info (string): information about the operation performed
  • changes (*UndefinedHash): hash of changed effected
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object itself
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/dataprovider/apps/{app}/actions

This URI path provides access to data provider application action functionality

GET /api/v8/dataprovider/apps/{app}/actions

Description
Returns info about the current DataProvider application actions
Arguments
Return Value
This API returns a value of type *list<DataProviderActionInfo>: list of all actions on each application

/api/v8/dataprovider/apps/{app}/actions/{action}

This URI path provides access to data provider functionality for a specific application action

GET /api/v8/dataprovider/apps/{app}/actions/{action}

Description
Returns info about the current DataProvider application action
Arguments
Return Value
This API returns a DataProviderActionInfo hash with the following keys (action information):
  • app (string): the application name
  • action (string): the unique action name in the application
  • subtype (*string): the subtype for the data provider provided by the connection
  • path (string): the data provider path for the action
  • path_vars (*PathVarSet): descriptions for any path variables
    • display_name (string): the display name of the path var
    • short_desc (string): short description of the path var in plain text
    • desc (string): description of the path var with markdown formatting
    • example_value (*string): any exmple value for the path var
  • display_name (string): the name of the action that will be displayed to users
  • short_desc (string): the action's short description in plain text
  • desc (string): the action's long description with markdown formatting
  • action_code (int): the action's code
  • action_code_str (string): a string description of the action code
  • action_val (*string): the action value (message or event type)
  • cls (*string): the class name for applications with no schema
  • data_dependent_options (bool): if the action contains data-dependent option definitions
  • options (*ActionOptionSet): options required to create the action
    • app (string): the application name
    • action (string): the action name
    • type (string): data type of the option
    • display_name (string): the display name of the option
    • short_desc (string): short description of the option in plain text
    • desc (string): description of the option with markdown formatting
    • preselected (*bool): if the option should be preselected by the front end
    • supports_expressions (*bool): if the option value supports expression evaluation
    • supports_templates (*bool): if the option value supports template expansion
    • required (*bool): is the option required?
    • required_groups (*list<string>): any groups of required options that this option is a member of
    • arg_schema (*string): a reference to an arg_schema that can be returned with a REST call to GET /api/latest/dataprovider/arg_schemas/_ref_
    • element_type (*string): the name of the list element type, if any
    • default_value (auto): any default value for the option
    • default_value_desc (*string): the description for the default value
    • readonly (*bool): if the option is read only
    • sensitive (*bool): is the value sensitive?
    • multiselect (*bool): are allowed values the allowed values for a list type?
    • allowed_values (*list<AllowedValueInfo>): allowed values for the option
    • allowed_values_creatable (*bool): can the value be a value not in allowed_values?
    • example_value (auto): an example value for the option
    • loc (*string): any option-specific location hint for the value when executing the action
    • value (auto): the value of the option, if any
    • depends_on (*list<auto>): any other option(s) that this option depends on for its value or allowed values
    • sort (int): sort key for option order
    • has_dependents (*bool): if any other options depend on this one
    • disallow_template (*bool): disallow templates on this option
    • messages (*list<UiMessageHash>): messages related to the option
    • metadata (*UndefinedHash): any additional data about the option
    • disabled (*bool): if the option is disabled
    • on_change (*list<string>): a list of actions for the front-end to perform if the option changes
    • structural_determinate (*bool): if True then the value of this option determines the presence (or
  • options_url (string): the URL to the API to verify action options
  • exec_url (string): the URL to the API to execute actions
  • output_type (*ActionOutputTypeInfo): information about the action's output type, if any
    • name (string): the name of the type
    • display_name (string): the display name of the type
    • short_desc (string): the short plain-text description of the type
    • desc (string): the full description of the type with markdown formatting
    • type (string): the name of the Qore underlying type for this type
    • fields (*ActionOutputFieldInfo): a hash keyed by field name of fields supported by the type
      • key (ActionOutputInfo): ActionOutputInfo value

POST /api/v8/dataprovider/apps/{app}/actions/{action}?action=createConnection

Description
Creates a new connection for the application
Arguments
This API takes the following hash argument:
  • options (*UndefinedHash): options and values to use
Return Value
This API returns a ConnectionCreationInfo hash with the following keys (connection creation info):
  • name (string): the new connection name
  • desc (string): the new connection description
  • id (int): the new connection ID
  • display_name (string): the display name for the connection
  • short_desc (string): the short description for the connection
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/dataprovider/apps/{app}/actions/{action}?action=exec

Description
Execute the current action; if the action is an API call, the API call is performed and the result is returned to the called; if the action is a message, the message is sent; if the action is an event, then the event data is returned. Any arguments or parameters with missing data will have their data filled with generated information if generate is True
Arguments
This API takes the following hash arguments:
  • options (*StringHash): options and values to use including qorus_app_connection; these are the options from the PUT getOptions() API also including any arguments for making the call, sending the message, etc
    • key (string): string value
  • generate (*bool): if True, then missing argument values will be generated
Return Value
This API returns a value of type auto: the result of executing the action
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/dataprovider/apps/{app}/actions/{action}?action=getCreateConnectionOptions

Description
Returns info about options required to create a new connection for the current action
Arguments
This API takes the following hash argument:
  • options (*UndefinedHash): options and values to use
Return Value
This API returns a ConnectionOptionSet hash with the following keys (connection option info; keys are option names):
  • type (string): data type of the option
  • display_name (string): the display name of the option
  • short_desc (string): short description of the option in plain text
  • desc (string): description of the option with markdown formatting
  • required (*bool): is the option required?
  • required_groups (*list<string>): any groups of required options that this option is a member of
  • arg_schema (*UndefinedHash): description of any subfields required for this option
  • default_value (auto): any default value for the option
  • default_value_desc (*string): the description for the default value
  • readonly (*bool): if the option is read only
  • sensitive (*bool): is the value sensitive?
  • multiselect (*bool): are allowed values the allowed values for a list type?
  • allowed_values (*list<AllowedValueInfo>): allowed values for the option
  • allowed_values_creatable (*bool): can the value be a value not in allowed_values?
  • example_value (*string): an example value for the option
  • subst_env_vars (bool): will environment variables in string values be substituted?
  • freeform (bool): modifier for the file-as-string type: can a freeform location option be returned?
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/dataprovider/apps/{app}/actions/{action}?action=getOptions

Description
Returns info about the current DataProvider application action with detailed option information
Arguments
This API takes the following hash argument:
  • options (*StringHash): options and values to use
    • key (string): string value
Return Value
This API returns a DataProviderOptionInfo hash with the following key (action information):
  • options (*ActionOptionSet): Action option required to create the data provider
    • app (string): the application name
    • action (string): the action name
    • type (string): data type of the option
    • display_name (string): the display name of the option
    • short_desc (string): short description of the option in plain text
    • desc (string): description of the option with markdown formatting
    • preselected (*bool): if the option should be preselected by the front end
    • supports_expressions (*bool): if the option value supports expression evaluation
    • supports_templates (*bool): if the option value supports template expansion
    • required (*bool): is the option required?
    • required_groups (*list<string>): any groups of required options that this option is a member of
    • arg_schema (*string): a reference to an arg_schema that can be returned with a REST call to GET /api/latest/dataprovider/arg_schemas/_ref_
    • element_type (*string): the name of the list element type, if any
    • default_value (auto): any default value for the option
    • default_value_desc (*string): the description for the default value
    • readonly (*bool): if the option is read only
    • sensitive (*bool): is the value sensitive?
    • multiselect (*bool): are allowed values the allowed values for a list type?
    • allowed_values (*list<AllowedValueInfo>): allowed values for the option
    • allowed_values_creatable (*bool): can the value be a value not in allowed_values?
    • example_value (auto): an example value for the option
    • loc (*string): any option-specific location hint for the value when executing the action
    • value (auto): the value of the option, if any
    • depends_on (*list<auto>): any other option(s) that this option depends on for its value or allowed values
    • sort (int): sort key for option order
    • has_dependents (*bool): if any other options depend on this one
    • disallow_template (*bool): disallow templates on this option
    • messages (*list<UiMessageHash>): messages related to the option
    • metadata (*UndefinedHash): any additional data about the option
    • disabled (*bool): if the option is disabled
    • on_change (*list<string>): a list of actions for the front-end to perform if the option changes
    • structural_determinate (*bool): if True then the value of this option determines the presence (or
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/dataprovider/apps/{app}/actions/{action}?action=outputType

Description
Returns info about the output type of the action
Arguments
Return Value
This API returns a DataProviderActionOutputTypeInfo hash; keys have the following format:
  • any (auto): action information

PUT /api/v8/dataprovider/apps/{app}/actions/{action}?action=updateConnection

Description
Updates an existing connection for the application
Arguments
This API takes the following hash argument:
  • options (*UndefinedHash): attributes to update on the connection; at least either the id or name attributes must be present to identify the connection; if id is present, then name can be used to rename the connection
Return Value
This API returns a ConnectionUpdateInfo hash with the following keys (connection creation info):
  • info (string): information about the operation performed
  • changes (*UndefinedHash): hash of changed effected
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object itself
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/dataprovider/arg_schemas

This URI path provides APIs related arg schemas

GET /api/v8/dataprovider/arg_schemas

Description
Retrieves type information about complex data types
Arguments
This API takes no arguments
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
  • any (auto): description of fields in the schema

/api/v8/dataprovider/arg_schemas/{schema}

This URI path provides APIs related to a specific arg schema

GET /api/v8/dataprovider/arg_schemas/{schema}

Description
Retrieves type information about complex data types
Arguments
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
  • any (auto): description of fields in the schema

/api/v8/dataprovider/basetypes

This URI path provides access to base data type information

GET /api/v8/dataprovider/basetypes

Description
Returns a list of base data types
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):

/api/v8/dataprovider/basetypes/{type}

This URI path provides access to base data type information for a specific type

/api/v8/dataprovider/basetypes/{type}/type

This URI path provides access information for a particular data type

GET /api/v8/dataprovider/basetypes/{type}/type

Description
Returns data type information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/browse

This URI path provides the root URI for browsing for types and data providers

GET /api/v8/dataprovider/browse

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

PUT /api/v8/dataprovider/browse?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

/api/v8/dataprovider/browse/connection

This URI path provides the root URI for browsing data providers from user connections

GET /api/v8/dataprovider/browse/connection

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/connection

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/connection?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

PUT /api/v8/dataprovider/browse/connection?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

/api/v8/dataprovider/browse/connection/{connection}

This URI path provides the root URI for browsing a data provider created from a user connection

GET /api/v8/dataprovider/browse/connection/{connection}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/connection/{connection}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/connection/{connection}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/connection/{connection}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

/api/v8/dataprovider/browse/connection/{connection}/info

DELETE /api/v8/dataprovider/browse/connection/{connection}/info

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/connection/{connection}?action=info

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/connection/{connection}/info?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/browse/connection/{connection}/info?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

PUT /api/v8/dataprovider/browse/connection/{connection}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/dataprovider/browse/connection/{connection}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/dataprovider/browse/connection/{connection}/info?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/connection/{connection}/info?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/connection/{connection}/info?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/connection/{connection}/info?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/connection/{connection}/info?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/connection/{connection}/info?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/connection/{connection}/info?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/dataprovider/browse/connection/{connection}/info/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/dataprovider/browse/connection/{connection}/info/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/dataprovider/browse/connection/{connection}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/dataprovider/browse/connection/{connection}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/browse/datasource

This URI path provides the root URI for browsing data providers from datasources

GET /api/v8/dataprovider/browse/datasource

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/datasource

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/datasource?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

PUT /api/v8/dataprovider/browse/datasource?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

/api/v8/dataprovider/browse/datasource/{datasource}

This URI path provides the root URI for browsing a data provider created from datasources

GET /api/v8/dataprovider/browse/datasource/{datasource}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/datasource/{datasource}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/datasource/{datasource}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/datasource/{datasource}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

/api/v8/dataprovider/browse/datasource/{datasource}/info

DELETE /api/v8/dataprovider/browse/datasource/{datasource}/info

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/datasource/{datasource}?action=info

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/dataprovider/browse/datasource/{datasource}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/dataprovider/browse/datasource/{datasource}/info?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/datasource/{datasource}/info?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/datasource/{datasource}/info?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/datasource/{datasource}/info?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/datasource/{datasource}/info?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/dataprovider/browse/datasource/{datasource}/info/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/dataprovider/browse/datasource/{datasource}/info/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/dataprovider/browse/datasource/{datasource}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/dataprovider/browse/datasource/{datasource}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/browse/factory

This URI path provides the root URI for browsing data provider factories

GET /api/v8/dataprovider/browse/factory

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/factory

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/factory?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

PUT /api/v8/dataprovider/browse/factory?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

/api/v8/dataprovider/browse/factory/{provider}

This URI path provides the root URI for browsing a data provider create from a data provider factory

GET /api/v8/dataprovider/browse/factory/{provider}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/factory/{provider}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/factory/{provider}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/factory/{provider}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

/api/v8/dataprovider/browse/factory/{provider}/info

DELETE /api/v8/dataprovider/browse/factory/{provider}/info

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/factory/{provider}?action=info

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/factory/{provider}/info?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/browse/factory/{provider}/info?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

PUT /api/v8/dataprovider/browse/factory/{provider}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/dataprovider/browse/factory/{provider}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/dataprovider/browse/factory/{provider}/info?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/factory/{provider}/info?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/factory/{provider}/info?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/factory/{provider}/info?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/factory/{provider}/info?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/factory/{provider}/info?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/factory/{provider}/info?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/dataprovider/browse/factory/{provider}/info/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/dataprovider/browse/factory/{provider}/info/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/dataprovider/browse/factory/{provider}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/dataprovider/browse/factory/{provider}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/browse/remote

This URI path provides the root URI for browsing data providers from remote Qorus connections

GET /api/v8/dataprovider/browse/remote

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/remote

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/remote?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

PUT /api/v8/dataprovider/browse/remote?action=info

Description
Returns information about the current navigation node
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNavInfo hash with the following key (a hash with basic info about the current data provider nav node):
  • name (string): the name of the node

/api/v8/dataprovider/browse/remote/{remote}

This URI path provides the root URI for browsing a data provider created from a remote Qorus connection

GET /api/v8/dataprovider/browse/remote/{remote}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/remote/{remote}

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/remote/{remote}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/remote/{remote}?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

/api/v8/dataprovider/browse/remote/{remote}/info

DELETE /api/v8/dataprovider/browse/remote/{remote}/info

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/remote/{remote}?action=info

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

PUT /api/v8/dataprovider/browse/remote/{remote}/info?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/browse/remote/{remote}/info?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

PUT /api/v8/dataprovider/browse/remote/{remote}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/dataprovider/browse/remote/{remote}/info?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/dataprovider/browse/remote/{remote}/info?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/remote/{remote}/info?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/remote/{remote}/info?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/browse/remote/{remote}/info?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/browse/remote/{remote}/info?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/remote/{remote}/info?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/browse/remote/{remote}/info?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/dataprovider/browse/remote/{remote}/info/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/dataprovider/browse/remote/{remote}/info/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/dataprovider/browse/remote/{remote}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/dataprovider/browse/remote/{remote}/info/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/browse/type

This URI path provides the root URI for browsing data types

GET /api/v8/dataprovider/browse/type

Description
Returns information on available paths to child types, if any
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

PUT /api/v8/dataprovider/browse/type

Description
Returns information on available paths to types or data providers according to the requesting context
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderBrowseNodeInfo hash with the following keys (a hash providing information about the current node):
  • type (string): one of the following: nav: a navigation node, data-provider: a data provider, type: a data type
  • children (list<DataProviderChildBrowseInfo>): a list of children of the current node
  • matches_context (*bool): if True then the node is a match for the search context

GET /api/v8/dataprovider/browse/type?action=info

Description
Returns information about the current DataProvider type
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): a hash with basic info about the current data provider type, if the node has a type, otherwise with basic information about the nav node

PUT /api/v8/dataprovider/browse/type?action=info

Description
Returns information about the current DataProvider
Arguments
This API takes the following hash argument:
  • context (*string): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): a hash with basic info about the current data provider type, if the node has a type, otherwise with basic information about the nav node

/api/v8/dataprovider/dataproviders

This URI path provides access to functionality related to listing available data providers

GET /api/v8/dataprovider/dataproviders

Description
Returns a list of available data providers

/api/v8/dataprovider/dataproviders/.../{name}

This URI path provides access to functionality related to listing available data providers

GET /api/v8/dataprovider/dataproviders/.../{name}

Description
Returns a list of available data providers

GET /api/v8/dataprovider/dataproviders/.../{name}?action=info

Description
Returns data provider information

/api/v8/dataprovider/dataproviders/.../{name}/events

This URI path provides access to functionality related to listing available events for a data provider

GET /api/v8/dataprovider/dataproviders/.../{name}/events

Description
Returns a hash of data provider messages

PUT /api/v8/dataprovider/dataproviders/.../{name}/events

Description
Returns a hash of data provider messages

/api/v8/dataprovider/dataproviders/.../{name}/messages

This URI path provides access to functionality related to listing available messages for a data provider

GET /api/v8/dataprovider/dataproviders/.../{name}/messages

Description
Returns a hash of data provider messages

PUT /api/v8/dataprovider/dataproviders/.../{name}/messages

Description
Returns a hash of data provider messages

/api/v8/dataprovider/dataproviders/connection

This URI path provides access to functionality related to listing available data providers

GET /api/v8/dataprovider/dataproviders/connection

Description
Returns a list of available data providers

/api/v8/dataprovider/dataproviders/datasource

This URI path provides access to functionality related to listing available data providers

GET /api/v8/dataprovider/dataproviders/datasource

Description
Returns a list of available data providers

/api/v8/dataprovider/dataproviders/qorus

This URI path provides access to functionality related to listing available data providers

GET /api/v8/dataprovider/dataproviders/qorus

Description
Returns a list of available data providers

/api/v8/dataprovider/factories

This URI path provides access to data factory information

GET /api/v8/dataprovider/factories

Description
Returns data factory information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • context: if "api" then only factories suitable for API management are returned, if "apicall", then only factories suitable for making API calls are returned
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of data provider factory names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings of data provider factory information is returned

/api/v8/dataprovider/factories/{factory}

This URI path provides access to data factory information

GET /api/v8/dataprovider/factories/{factory}

Description
Returns data factory information

GET /api/v8/dataprovider/factories/{factory}?action=providerExampleOutput

Description
Returns example records from the example input and factory constructor options
Arguments
This API takes the following hash arguments:
  • encoded_example: base-64-encoded string example input
  • provider_yaml_options: a string in the following format giving factory provider constructor options: key = base-64-encoded yaml value

/api/v8/dataprovider/factories/{factory}/provider

This URI path provides access to a data provider created from a data provider factory

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

DELETE /api/v8/dataprovider/factories/{factory}/provider

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/factories/{factory}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/factories/{factory}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/factories/{factory}/provider?action=Description

Description
Returns data provider information
Arguments
This API takes the following hash arguments:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

PUT /api/v8/dataprovider/factories/{factory}/provider?action=apiEndpoints

Description
Returns a list of request/response endpoint information for the data provider
Arguments
This API takes the following hash arguments:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
  • soft (*bool): soft types are returned
  • provider_options (*UndefinedHash): a hash of constructor options for a data provider when following the URI path through a data provider factory that takes constructor options
Return Value
This API returns a value of type list<EndpointInfo>: a list of API endpoints supported by the data provider

DELETE /api/v8/dataprovider/factories/{factory}/provider?action=child

Description
Permanently deletes the given child data provider
Return Value
This API returns a hash with the following key:
  • name: (required string) the name of the child provider to delete
Errors
  • 400 Bad Request: returned if the request has no name key or if the data provider does not support the current operation
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

GET /api/v8/dataprovider/factories/{factory}/provider?action=childDetails

Description
Returns data provider information
Arguments
This API takes the following hash argument:
  • context (*list<string>): one of the following: api: when browsing for a request-response data provider, record: when browsing for a record-based data provider, event: when browsing for a data provider that can function as an observable event source, message: when browsing for a data provider that supports sending messages, transaction: when browsing for a data provider that supports transaction management, type: when browsing for a type
Return Value
This API returns a DataProviderChildDetailInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • children (*list<DataProviderSummaryInfo>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information

POST /api/v8/dataprovider/factories/{factory}/provider?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=field

Description
This API updated a field in the provider, if the data provider supports updating fields
Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • name: (required string) the current name of the field
  • new_name: (optional string) the new name of the field
  • field: (optional hash) a hash with the following keys:
    • type: (string) the type of the field
    • desc: (string) field description
    • default_value: (value of field's type) the default value of the field if not present
    • opts: (hash) any options for the given type
  • opts: (optional hash) any field update options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no old_name key or if the data provider does not support the current operation
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

DELETE /api/v8/dataprovider/factories/{factory}/provider?action=field

Description
Permanently deletes the given field from the data provider
Return Value
This API returns a hash with the following key:
  • name: (required string) the name of the field to delete
Errors
  • 400 Bad Request: returned if the request has no name key or if the data provider does not support the current operation
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/factories/{factory}/provider?action=fieldAdd

Description
This API adds a field to the provider, if the data provider supports adding fields
Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • name: (required string) the name of the new child provider
  • field: (required hash) a hash with the following keys:
    • type: (string) the type of the field
    • desc: (string) field description
    • default_value: (value of field's type) the default value of the field if not present
    • opts: (hash) any options for the given type
  • opts: (optional hash) any field creation options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no name or fields keys or if the data provider does not support the current operation
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/factories/{factory}/provider?action=providerCreate

Description
This API creates a child data provider, if the data provider supports child creation
Arguments
This API takes the following hash arguments:
  • name (string): the name of the new child provider
  • fields (QorusNewFieldSetInfo): the set of fields making up the new record where keys are field names and values describe each field
    • type (string): the type of the field
    • desc (string): field description
    • default_value (auto): the default value of the field if not present; the value must be compatible with the field's type
    • opts (*hash<auto>): any options for the given type
Return Value
This API returns a value of type string: the string "OK"
Errors
  • 400 Bad Request: returned if the request has no name or fields keys or if the data provider does not support the current operation
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

POST /api/v8/dataprovider/factories/{factory}/provider?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=search

Description
Searches for records matching the search parameters
Arguments
This API takes the following hash arguments:
  • provider_options (*UndefinedHash): any options to be passed to a factory creation method when accessing this URI endpoint through a factory
  • where_cond (*UndefinedHash): the where CreatorJobDefinitionRestClass
  • search_options (*UndefinedHash): any search options
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
  • any (auto): list of record hashes matching the search parameters given by where_cond
Errors
  • 400 Bad Request: the data provider does not support searching
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

GET /api/v8/dataprovider/factories/{factory}/provider?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=searchSingleRecord

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a single record matching the search parameters given by where_cond or no value
Errors
  • 400 Bad Request: data provider does not support searching or search matches multiple records
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=searchStream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/dataprovider/factories/{factory}/provider?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/factories/{factory}/provider?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/dataprovider/factories/{factory}/provider?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/dataprovider/factories/{factory}/provider/.../request-fields

This URI path provides access information for a particular data request data type

/api/v8/dataprovider/factories/{factory}/provider/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/dataprovider/factories/{factory}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/dataprovider/factories/{factory}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/dataprovider/types

This URI path provides access to data type information

DELETE /api/v8/dataprovider/types

Description
Deletes the data type
Errors
  • 400 Bad Request: returned if the entry has no type to delete
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation or if the type is a base type
Note

GET /api/v8/dataprovider/types

Description
Returns information for the current data type entry

POST /api/v8/dataprovider/types

Description
Creates a new data type
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • path: (*string) the relative path from the current entry to the new type (ex: "my-types/project-x/my-type")
  • type: (hash) a hash with the following keys:
    • name: (string) the type name
    • options: (*hash) a hash of type options
    • fields: (*hash) a hash of fields where names are field names and values are hashes with the following keys:
      • type: (hash) as above
      • desc: (*string) a description for the field
      • default: (*string) a default value for the field serialization as YAML
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 403 Forbidden: TYPE-LOCK-ERROR: a static/base type already exists with the given path
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and and the user does not have sufficient privileges for the operation
Note

GET /api/v8/dataprovider/types?action=childDetails

Description
Returns information for the current data type entry with details for children

GET /api/v8/dataprovider/types?action=listAll

Description
Returns information about the current data type

GET /api/v8/dataprovider/types?action=type

Description
Returns information about the current data type
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper
Errors
  • 404 Not Found: returned if the current entry has no type

/api/v8/dataprovider/types/.../{type}/type

This URI path provides access information for a particular data type

GET /api/v8/dataprovider/types/.../{type}/type

Description
Returns data type information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper
  • context: optional; if the value is "ui", then the return format will be in a format suitable for the UI

GET /api/v8/dataprovider/types/.../{type}/type?action=compare

Description
Takes a type argument and returns a boolean value:
  • True: the type given as an argument is compatible with the current type; i.e. a variable of the current type can be assigned to a value corresponding to the type passed as an argument
  • False: the type given as an argument is not compatible with the current type; i.e. a variable of the current type cannot be assigned to a value corresponding to the type passed as an argument without type errors
Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • type: required; a string path to the other type (ex: "my/other/type")
Errors
  • 400 Bad Request: missing or invalid "type" argument
  • 404 Not Found: the given type cannot be found

/api/v8/debug

This REST URI path provides actions and information related to Qorus system debugging

/api/v8/debug/development

This REST URI path provides information related to Qorus remote development data

/api/v8/debug/interface-serialization

This REST URI path provides information related to Qorus internal interface action serialization data

/api/v8/debug/order-stats

This REST URI path provides information related to the internal Qorus service cache

/api/v8/debug/order-stats-summary

This REST URI path provides summary information related to internal Qorus order statistics processing data

/api/v8/debug/sync-cache

This REST URI path provides information related to internal Qorus synchronization event cache data

/api/v8/debug/sync-summary

This REST URI path provides information related to internal Qorus synchronization event cache summary info

/api/v8/debug/threads

This REST URI path provides information related to Qorus threads

GET /api/v8/debug/threads

Description
Returns a hash keyed by thread ID where the values are lists describing the call stack for the thread
Return Value
This API returns a hash keyed by thread ID where the values are lists of REST Debug Callstack Hash elements showing the call stack for the thread sorted from most recent to oldest

/api/v8/debug/threads/{tid}

This REST URI path provides actions and information related to a single Qorus thread

GET /api/v8/debug/threads/{tid}

Description
Returns a hash describing the current thread
Return Value
This API returns a list of REST Debug Callstack Hash elements showing the call stack sorted from most recent to oldest

/api/v8/debug/workflow-control

This REST URI path provides information related to Qorus internal workflow control data

/api/v8/development

This URI path provides remote development for Qorus.

GET /api/v8/development

Description
Returns all API paths of development API path.
Return Value
If success 200 OK and list of the all API paths.

/api/v8/development/delete

This URI path provides API to delete interfaces from Qorus.

POST /api/v8/development/delete

Description
Asynchronously creates a delete request and returns id and resource location.
Arguments
This API takes the following argument as method body (all arguments are optional, but at least one must be presented otherwise 400 BAD-REQUEST error will be returned)
  • function: optional; list of functions to be deleted
  • class: optional; list of classes to be deleted
  • constant: optional; list of constants to be deleted
  • service: optional; list of services to be deleted
  • step: optional; list of workflow steps to be deleted
  • wfinstances: optional; list of workflow instances to be deleted
  • workflow: optional; list of workflows to be deleted

Each element of the above lists is a hash with the following keys:

  • name: required; name of the interface.
  • version: required; version of the interface. Also each interface can be deleted by providing only its id:
  • id: required; id of the interface.
  • method: optional; list of service methods to be deleted. Each element is a hash with the following keys:
    • name: required; name of the service.
    • version: required; version of the service.
    • method-name: required; name of the method. Also methods can be deleted by providing only its id:
  • id: required; id of the method.

The follow hash keys are accepted and take only the object name for deletion:

  • datasource: optional; list of datasource connections to be deleted.
  • event: optional; list of events to be deleted.
  • fsm: optional; list of FSMs to be deleted
  • job: optional; list of jobs to be deleted.
  • jobinstances: optional; list of job instances to be deleted.
  • mapper: optional; list of mappers to be deleted.
  • pipeline: optional; list of pipelines to be deleted
  • queue: optional; list of queues to be deleted.
  • remote: optional; list of remote connections to be deleted.
  • uconn: optional; list of user connections to be deleted.
  • vmap: optional; list of value maps to be deleted.

Each element of the above lists is a hash with the following keys:

  • name: required; name of the value map. Also each interface from the above list (except for all connections) can be deleted by providing only its id:
  • id: required; id of the interface.
  • options: optional; hash of delete options. List of valid options:
    • reload: reload interfaces in the server
    • verbosity-level: sets verbosity level (greater value = more info)
Note
By default all options are set to False and verbosity level is set to 0.

Example of POST request:

{
"workflow":
[
{
"name" : "workflow1",
"version" : "1.0"
},
{
"id" : "4"
}
],
"method": [
{
"service-name": "service1",
"version": "1.0",
"method-name": "method1"
}
],
"options": {
"reload": true,
"verbosity-level": 2
}
}
Return Value
If success 202 Accepted, resource location and id of the created request is returned. In case of fail 400 bad request error is returned.

/api/v8/development/delete/{id}

This URI path implements delete request to Qorus.

DELETE /api/v8/development/delete/{id}

Description
Cancel a delete request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to be canceled.
Return Value
If success 200 OK, in case of fail one of the error codes: 410, 403, 404 and string of error description.

GET /api/v8/development/delete/{id}

Description
Returns status of a delete request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to obtain status.
Return Value
If success 200 OK and hash of the request status, in case of fail 404 not found error. The status hash has the following keys:
  • status: the status of the request:
    • QUEUED - the request is waiting in the queue
    • IN_PROGRESS - the request is in progress
    • CANCELED - the request has been canceled by the user
    • FAILED - the request has failed
    • FINISHED - the request is finished
  • exit_code: the exit code of the request
  • stderr: the standard error output
  • stdout: the standard output
  • created: the date/time the request was created

/api/v8/development/deploy

This URI path provides remote deployment for Qorus.

POST /api/v8/development/deploy

Description
Asynchronously creates a deployment request and returns id and resource location.
Arguments
This API takes the following argument as method body:
  • files: required; list of files to be deployed. Each element is a hash with in the following format:
    • file_name: string.
    • file_content: base64 encoded string.
  • options: optional; hash of deployment options. List of valid options:
    • allow-redef: allow dangerous workflow redefinitions
    • force: force schema verification/downgrade with user schemas
    • validate: validate all functions recursively
    • reload: reload interfaces in the server
    • verbosity-level: sets verbosity level (greater value = more info)
Note
By default all options are set to False and verbosity level is set to 0.

Example of POST request:

{
"files":
[
{
"file_name": "file1.txt",
"file_content": "dGV4dCBmcm9tIHRtcCAw"
},
{
"file_name": "path/file2.txt",
"file_content": "dGV4dCBmcm9tIHRtcCAx"
},
],
"options": {
"allow-redef": true,
"force": false,
"validate": true,
"reload": true,
"verbosity-level": 2
}
}

File content is base64 encoded. Options parameter is optional.

Return Value
If success 202 Accepted, resource location and id of the created request is returned. In case of fail 400 bad request error is returned.

/api/v8/development/deploy/{id}

This URI path implements deployment request to Qorus.

DELETE /api/v8/development/deploy/{id}

Description
Cancel a deployment request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to be canceled.
Return Value
If success 200 OK, in case of fail one of the error codes: 410, 403, 404 and string of error description.

GET /api/v8/development/deploy/{id}

Description
Returns status of a deployment request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to obtain status.
Return Value
If success 200 OK and hash of the request status, in case of fail 404 not found error. The status hash has the following keys:
  • status: the status of the request:
    • QUEUED - the request is waiting in the queue
    • UPLOADING - the files are uploading
    • UPLOADED - all files are uploaded to the server
    • IN_PROGRESS - the request is in progress
    • CANCELED - the request has been canceled by the user
    • FAILED - the request has failed
    • FINISHED - the request is finished
  • exit_code: the exit code of the request
  • stderr: the standard error output
  • stdout: the standard output
  • created: the date/time the request was created

/api/v8/development/release

This URI path provides remote release for Qorus.

POST /api/v8/development/release

Description
Asynchronously creates a release request and returns id and resource location.
Arguments
This API takes the following argument as method body:
  • files: required; list of files to be released. Files should be archived in tar.bz2 or tar.gz format. Element is a hash with in the following format:
    • file_name: string file name of the archive.
    • file_content: base64 encoded string content of the archive. Archive should contain a .qrf file.
  • options: optional; hash of deployment options. List of valid options:
    • allow-redef: allow dangerous workflow redefinitions
    • force: force schema verification/downgrade with user schemas
    • validate: validate all functions recursively
    • reload: reload interfaces in the server
    • verbosity-level: sets verbosity level (greater value = more info)
Note
By default all options are set to False and verbosity level is set to 0.

Example of POST request:

{
"files":
[{
"file_name": "arch.tar.bz2",
"file_content": "dGV4dCBmcm9tIHRtcCAw"
}],
],
"options": {
"verbosity-level": 2
}
}

File content is base64 encoded. Options parameter is optional.

Return Value
If success 202 Accepted, resource location and id of the created request is returned. In case of fail 400 bad request error is returned.

/api/v8/development/release/{id}

This URI path implements release request to Qorus.

DELETE /api/v8/development/release/{id}

Description
Cancel a release request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to be canceled.
Return Value
If success 200 OK, in case of fail one of the error codes: 410, 403, 404 and string of error description.

GET /api/v8/development/release/{id}

Description
Returns status of a release request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to obtain status.
Return Value
If success 200 OK and hash of the request status, in case of fail 404 not found error. The status hash has the following keys:
  • status: the status of the request:
    • QUEUED - the request is waiting in the queue
    • UPLOADING - the files are uploading
    • UPLOADED - all files are uploaded to the server
    • IN_PROGRESS - the request is in progress
    • CANCELED - the request has been canceled by the user
    • FAILED - the request has failed
    • FINISHED - the request is finished
  • exit_code: the exit code of the request
  • stderr: the standard error output
  • stdout: the standard output
  • created: the date/time the request was created

/api/v8/development/test

This URI path provides API to execute qtests.

POST /api/v8/development/test

Description
Asynchronously creates a test request and returns id and resource location.
Arguments
This API takes the following argument as method body:
  • files: required; list of qtest files. Each element is a hash with in the following format:
    • file_name: string.
    • file_content: base64 encoded string.
  • options: optional; hash of delete options. List of valid options:
    • continue_on_error: if True and one of the tests fails, server will continue on execution of the rest.
Note
By default all options are set to False.

Example of POST request:

{
"files":
[
{
"file_name": "file1.qtest",
"file_content": "dGV4dCBmcm9tIHRtcCAw",
"args": {
"arg1": "value1",
"arg2": "value2"
}
},
{
"file_name": "path/file2.qtest",
"file_content": "dGV4dCBmcm9tIHRtcCAx"
},
],
options: {
"continue_on_error": True
}
}

File content is base64 encoded. Options parameter is optional.

Return Value
If success 202 Accepted, resource location and id of the created request is returned. In case of fail 400 bad request error is returned.

/api/v8/development/test/{id}

This URI path implements test request to Qorus.

DELETE /api/v8/development/test/{id}

Description
Cancel a delete request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to be canceled.
Return Value
If success 200 OK, in case of fail one of the error codes: 410, 403, 404 and string of error description.

GET /api/v8/development/test/{id}

Description
Returns status of a delete request with given request id.
Arguments
This API takes the following argument as URI arguments:
  • id: required; id of the request to obtain status.
Return Value
If success 200 OK and hash of the request status, in case of fail 404 not found error. The status hash has the following keys:
  • status: the status of the request:
    • QUEUED - the request is waiting in the queue
    • UPLOADING - the files are uploading
    • UPLOADED - all files are uploaded to the server
    • IN_PROGRESS - the request is in progress
    • CANCELED - the request has been canceled by the user
    • FAILED - the request has failed
    • FINISHED - the request is finished
  • exit_code: the exit code of the request
  • stderr: the standard error output
  • stdout: the standard output
  • created: the date/time the request was created

/api/v8/error-sets

This REST URI path provides actions and information about workflow error sets

GET /api/v8/error-sets

Description
Returns information about error sets
Arguments
This API takes no arguments
Return Value
This API returns a value of type *list<ErrorSetInfo>: information about the error sets

POST /api/v8/error-sets

Description
Creates a new error set
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the error set
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the error set with markdown formatting
  • errors (list<ErrorSetErrorInfo>): a list of error definition hashes
Return Value
This API returns a CreateErrorSetInfo hash with the following keys (a description of the new error set):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/error-sets?action=create

Description
Creates a new error set
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the error set
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the error set with markdown formatting
  • errors (list<ErrorSetErrorInfo>): a list of error definition hashes
Return Value
This API returns a CreateErrorSetInfo hash with the following keys (a description of the new error set):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/error-sets/{error-set}

This REST URI path provides actions and information about workflow error sets

DELETE /api/v8/error-sets/{error-set}

Description
Deletes the error set
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns an ErrorSetDeletionInfo hash with the following key (information about the error set that was deleted):
  • id (int): the ID of the error set that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such error set
Note
Requires one of the following permissions:

GET /api/v8/error-sets/{error-set}

Description
Returns information about the error set
Arguments
Return Value
This API returns an ErrorSetInfo hash with the following keys (information about the current error set):
  • errorid (int): the error set ID
  • name (string): the internal name for the error set
  • display_name (*string): the display name
  • short_desc (*string): the plain-text short description
  • description (string): the description for the error set with markdown formatting
  • errors (list<ErrorSetErrorInfo>): a list of error definition hashes

PUT /api/v8/error-sets/{error-set}

Description
Updates the current error set
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the error set; if not provided, the new name will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the error set
Return Value
This API returns an UpdateErrorSetInfo hash with the following keys (a description of the new error set):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/error-sets/{error-set}?action=clone

Description
Clones the current error set
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the error set; if not provided, the new name will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the error set
Return Value
This API returns a CloneErrorSetInfo hash with the following keys (a description of the new error set):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/error-sets/{error-set}?action=file

Description
Returns the error set as a file that can be saved

/api/v8/errors

This URI path provides actions and information related to workflow errors

GET /api/v8/errors

Description
Returns a list of information of workflow errors corresponding to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • errors: optional; a comma-separated string will be split into a list; the workflow errors
  • filter: optional; if "global" then only global errors will be listed; other values for this argument key are ignored; takes precendence over wf
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of error names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings with error names and brief info is returned
  • wf: optional; a workflow ID or name to use to filter the results with; ignored if filter = "global"
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Error Description Hash elements corresponding to the arguments

POST /api/v8/errors

Description
Creates a workflow error
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional bool) parsed with Qore::parse_boolean(); if True then the workflow error will be created as a workflow-specific error even if no global error exists; default if not present False; only used if workflowid also present
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
  • workflowid: (optional string) an optional workflow ID for potentially creating a workflow-specific workflow error definition
Return Value
This API returns a string giving the result of the operation; one of:
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "CREATED-GLOBAL": a new global error was created (only possible if forceworkflow is omitted or False) est)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 409 Conflict: ERROR-EXISTS: this exception is thrown if the workflow-specific error definition already exists
Note
  • requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
  • the default behavior of this API is to create a global error if no global error with the error name exists; in this case a workflow-specific error can be forced to be created by using the workflowid and forceworkflow options as described above

POST /api/v8/errors?action=createOrUpdate

Description
Creates or updates a workflow error
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional bool) parsed with Qore::parse_boolean(); if True then the workflow error will be created as a workflow-specific error even if no global error exists; default if not present False; only used if workflowid also present
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
  • workflowid: (optional string) an optional workflow ID for potentially creating a workflow-specific workflow error definition
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
  • "CREATED-GLOBAL": a new global error was created (only possible if forceworkflow is omitted or False)
  • "UNCHANGED-GLOBAL": the new global definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
  • the default behavior of this API is to create a global error if no global error with the error name exists; in this case a workflow-specific error can be forced to be created by using the workflowid and forceworkflow options as described above

PUT /api/v8/errors?action=reload

Description
Reloads all workflow error definitions from the DB
Return Value
This API returns a hash with the following keys:
  • global: gives the number of global error definitions loaded
  • workflow: gives the number of all workflow-specific error definitions loaded
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
See also

GET /api/v8/errors?action=search

Description
Returns a list of information of workflow errors corresponding to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • errors: a comma-separated string will be split into a list; the workflow errors to search for
Return Value
This API returns a list of REST Workflow Error Description Hash elements corresponding to the arguments

/api/v8/errors/global

This REST URI path provides actions and information related to global workflow errors

GET /api/v8/errors/global

Description
Returns a list of information of global workflow errors
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Error Description Hash elements for the global workflow errors corresponding to the arguments

POST /api/v8/errors/global

Description
Creates a global workflow error
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a the following string: "CREATED-GLOBAL" indicating that a new global workflow error was created
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: ERROR-EXISTS: this exception is thrown if the global workflow error already exists
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

POST /api/v8/errors/global?action=createOrUpdate

Description
Creates or updates a global workflow error
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-GLOBAL": the existing global error was updated
  • "CREATED-GLOBAL": a new global error was created
  • "UNCHANGED-GLOBAL": the new global definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

/api/v8/errors/global/{error}

This URI path provides actions and information related to a specific global workflow error

DELETE /api/v8/errors/global/{error}

Description
Permanently deletes the current workflow error
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

GET /api/v8/errors/global/{error}

Description
Returns a hash of information about the current workflow error
Return Value
Returns a REST Workflow Error Description Hash (REST API v1 and v2)

PUT /api/v8/errors/global/{error}

Description
Updates the current global workflow error with the new definition given as arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (string) the new description of the error
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-GLOBAL": the existing global error was updated
  • "CREATED-GLOBAL": a new global error was created (only possible in case of a race condition where the current error was deleted during this request)
  • "UNCHANGED-GLOBAL": the new global definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
See also

PUT /api/v8/errors/global/{error}?action=update

Description
Updates the current global workflow error with the new definition given as arguments
See also
This API is equivalent to PUT /api/errors/global/{error}; see that documentation for details.

/api/v8/errors/workflow

This URI path provides actions and information related to workflow-specific workflow-specific workflow errors across all workflows

GET /api/v8/errors/workflow

Description
Returns a list of information of workflow-specific workflow errors for all workflows
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Error Description Hash elements for the workflow errors for the current workflow corresponding to the arguments

/api/v8/errors/workflow/{id_or_name}

This URI path provides actions and information related to workflow-specific workflow errors for a particular workflow

GET /api/v8/errors/workflow/{id_or_name}

Description
Returns a list of information of workflow-specific workflow errors for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Error Description Hash elements for the workflow errors for the current workflow corresponding to the arguments

POST /api/v8/errors/workflow/{id_or_name}

Description
Creates a workflow-specific workflow error for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "CREATED-GLOBAL": a new global error was created (only possible if forceworkflow is omitted or False)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 409 Conflict: ERROR-EXISTS: this exception is thrown if the workflow-specific error definition already exists
Note

POST /api/v8/errors/workflow/{id_or_name}?action=createOrUpdate

Description
Creates or updates a workflow-specific workflow error for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

/api/v8/errors/workflow/{id_or_name}/{error}

This URI path provides actions and information related to a workflow-specific workflow error

DELETE /api/v8/errors/workflow/{id_or_name}/{error}

Description
Permanently deletes the current workflow error
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

GET /api/v8/errors/workflow/{id_or_name}/{error}

Description
Returns a hash of information about the current workflow error
Return Value
Returns a REST Workflow Error Description Hash

PUT /api/v8/errors/workflow/{id_or_name}/{error}

Description
Updates the current workflow-specific workflow error with the new definition given as arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (string) the new description of the error
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created (only possible in case of a race condition where the current error was deleted during this request)
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
See also

PUT /api/v8/errors/workflow/{id_or_name}/{error}?action=update

Description
Updates the current workflow-specific workflow error with the new definition given as arguments
See also
This API is equivalent to PUT /api/v3/errors/workflow/{id_or_name}/{error}; see that documentation for details.

/api/v8/errors/{error}

This URI path provides actions and information related to a specific workflow error

DELETE /api/v8/errors/{error}

Description
Permanently deletes the current workflow error
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

GET /api/v8/errors/{error}

Description
Returns a hash of information about the current workflow error
Return Value
Returns a REST Workflow Error Description Hash

PUT /api/v8/errors/{error}

Description
Updates the current workflow error with the new definition given as arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created (only possible in case of a race condition where the current error was deleted during this request)
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
  • "UPDATED-GLOBAL": the existing global error was updated
  • "CREATED-GLOBAL": a new global error was created (only possible in case of a race condition where the current error was deleted during this request)
  • "UNCHANGED-GLOBAL": the new global definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: ERROR-UPDATE-ERROR: invalid keys or key values provided in the error description hash
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
See also

PUT /api/v8/errors/{error}?action=update

Description
Updates the current workflow error
See also
This API is equivalent to PUT /api/errors/{error}; see that documentation for details.

/api/v8/exec

This URI path provides actions and information regarding workflow execution instances.

GET /api/v8/exec

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash v3, plus the following keys:
  • groups: list of interface groups that the workflow belongs to; each list element is a REST Interface Group Hash (may be empty)
  • alerts: a list of alerts raised against the workflow; each list element is a REST Alert Hash (may be empty)
  • log_url: a complete URL to the websocket source for the workflow log

GET /api/v8/exec?action=list

Description
Returns information about workflow execution instances.
See also
This API is equivalent to GET /api/exec; see that documentation for details.

PUT /api/v8/exec?action=stopAll

Description
Stops all workflow execution instances.
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances stopped
  • workflows: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • msg: a descriptive message about the workflows stopped
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances
Note

PUT /api/v8/exec?action=stopMany

Description
Manually stops one or more workflow execution instances.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • args: (required) one or more workflow names or IDs to stop
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances stopped
  • workflows: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • msg: a descriptive message describing the workflow execution instances that were stopped
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances
Note

/api/v8/exec/{id}

This URI path provides actions and information regarding a particular workflow execution instance.

GET /api/v8/exec/{id}

Return Value
This API returns a hash with the keys of REST Execution Instance Hash v3, plus the following keys:
  • groups: list of interface groups that the workflow belongs to; each list element is a REST Interface Group Hash (may be empty)
  • alerts: a list of alerts raised against the workflow; each list element is a REST Alert Hash (may be empty)
  • log_url: a complete URL to the websocket source for the workflow log

PUT /api/v8/exec/{id}?action=setOptions

Description
Sets workflow options; workflow options are now actually global for the given workflow; this API will set global options against the workflow and not just on the current execution instance level. If the workflow has an option list and any of the options are not valid for that workflow, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options to set against the workflow; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns a string confirming that the options have been set.
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 409 Conflict: WORKFLOW-OPTION-ERROR: invalid option for workflow or option cannot be overridden at the workflow level
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
Deprecated:
use PUT /api/workflows/{id_or_name}?action=setOptions instead

PUT /api/v8/exec/{id}?action=stop

Description
Manually stops the workflow execution instance.
Return Value
This API returns "OK" if successful.
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows/{id_or_name}?action=enable and PUT /api/workflows/{id_or_name}?action=disable instead of starting and stopping workflow execution instances
Note

/api/v8/exec/{workflowname}

This URI path provides actions and information about workflow execution instances for a particular workflow.

GET /api/v8/exec/{workflowname}

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash v3, plus the following keys:
  • groups: list of interface groups that the workflow belongs to; each list element is a REST Interface Group Hash (may be empty)
  • alerts: a list of alerts raised against the workflow; each list element is a REST Alert Hash (may be empty)
  • log_url: a complete URL to the websocket source for the workflow log

GET /api/v8/exec/{workflowname}?action=desc

Return Value
Returns a string describing the workflow.

PUT /api/v8/exec/{workflowname}?action=setOptions

Description
Sets workflow options; workflow options are now actually global for the given workflow; this API will set global options against the workflow and not on the execution instances. If the workflow has an option list and any of the options are not valid for that workflow, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options to set against the workflow; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns a hash keyed by execution instance ID of option set.
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 409 Conflict: WORKFLOW-OPTION-ERROR: invalid option for workflow or option cannot be overridden at the workflow level
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
Deprecated:
use PUT /api/workflows/{id_or_name}?action=setOptions instead

PUT /api/v8/exec/{workflowname}?action=stop

Description
Manually stops the workflow execution instances.
Return Value
This API returns a hash with the following key if there are execution instances:
  • stopped: the value is a descriptive string for the workflow
otherwise it returns a string "no instances to stop".
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows/{id_or_name}?action=enable and PUT /api/workflows/{id_or_name}?action=disable instead of starting and stopping workflow execution instances
Note

/api/v8/fsms

This REST API path provides actions and information related to Qorus Finite State Machines.

GET /api/v8/fsms

Description
Returns a list of hashes describing Finite State Machines in Qorus
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):

POST /api/v8/fsms

Description
Creates a new FSM from the parameters
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the FSM
  • display_name (*string): the new display name for the FSM; generated from name if necessary
  • short_desc (*string): the short plain-text description for the FSM
  • desc (string): the new description for the FSM with markdown formatting
  • groups (*list<string>): interface groups that the FSM belongs to
  • input_type (*UndefinedHash): the input type for the FSM
  • output_type (*UndefinedHash): the output type for the FSM
  • states (UndefinedHash): the state definitions for the FSM
  • options (*UndefinedHash): options for the FSM
  • autovar (*UndefinedHash): automatic variables for the FSM
  • localvar (*UndefinedHash): local variables for the FSM
  • globalvar (*UndefinedHash): global variables for the FSM
  • replace (*bool): if True the FSM will be replaced if it exists already
Return Value
This API returns a CreateFsmInfo hash with the following keys (the result of creating the FSM):
  • id (int): the FSM ID
  • name (string): the name of the FSM
  • display_name (string): the display name of the FSM
  • draft_id (string): the Qog draft ID created
  • issues (*string): any issues mapping the input to the Qog configuration
  • advice (*string): any advice on improving the input to achieve better results
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/fsms?action=create

Description
Creates a new FSM from the parameters
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the FSM
  • display_name (*string): the new display name for the FSM; generated from name if necessary
  • short_desc (*string): the short plain-text description for the FSM
  • desc (string): the new description for the FSM with markdown formatting
  • groups (*list<string>): interface groups that the FSM belongs to
  • input_type (*UndefinedHash): the input type for the FSM
  • output_type (*UndefinedHash): the output type for the FSM
  • states (UndefinedHash): the state definitions for the FSM
  • options (*UndefinedHash): options for the FSM
  • autovar (*UndefinedHash): automatic variables for the FSM
  • localvar (*UndefinedHash): local variables for the FSM
  • globalvar (*UndefinedHash): global variables for the FSM
  • replace (*bool): if True the FSM will be replaced if it exists already
Return Value
This API returns a CreateFsmInfo hash with the following keys (the result of creating the FSM):
  • id (int): the FSM ID
  • name (string): the name of the FSM
  • display_name (string): the display name of the FSM
  • draft_id (string): the Qog draft ID created
  • issues (*string): any issues mapping the input to the Qog configuration
  • advice (*string): any advice on improving the input to achieve better results
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/fsms?action=createDraftFromText

Description
Creates a new FSM draft from natural language input
Arguments
This API takes the following hash argument:
  • input (string): the plain-language text describing what the Qog should do
Return Value
This API returns a CreateFsmInfo hash with the following keys (the result of creating the Qog):
  • id (int): the FSM ID
  • name (string): the name of the FSM
  • display_name (string): the display name of the FSM
  • draft_id (string): the Qog draft ID created
  • issues (*string): any issues mapping the input to the Qog configuration
  • advice (*string): any advice on improving the input to achieve better results
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/fsms?action=exec

Description
Execute the given FSM configuration and return any output
Arguments
This API takes the following hash arguments:
  • fsm (UndefinedHash): the FSM configuration to execute
  • input_data (auto): any input data for the FSM
  • state_data (*bool): return information about state data in the response
Return Value
This API returns a FsmExecInfo hash with the following keys (the result of executing the FSM):
  • output_data (auto): any output data for the FSM
  • state_data (FsmStateDataInfo): a hash keyed by state ID where values are the last output data for each state with a sort key
    • sort (int): the sort key to provide order for the hash
    • success (bool): if the state was successfully executed or not
    • response (auto): the output data of the state, if any, and if there was no error
    • error (*string): any uncaught error raised by the state

PUT /api/v8/fsms?action=getStateData

Description
Returns output data for multiple states
Arguments
This API takes the following hash arguments:
  • fsm (UndefinedHash): complete FSM parsed file data
  • data_context (*string): the data type for any target field; if present, only compatible fields will be returned
  • current_state (*string): any current state so that only data from previous states will be returned
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): hash of state data keyed by state name
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/fsms/{fname}

This REST API path provides actions and information related to a particular Qorus Finite State Machine.

DELETE /api/v8/fsms/{fname}

Description
Deletes the current FSM
Arguments
Return Value
This API returns a FsmDeletionResult hash with the following key (FSM deletion info):
  • name (string): the name of the FSM deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such FSM
Note
Requires one of the following permissions:

GET /api/v8/fsms/{fname}

Description
Returns the description of the Finite State Machine

PUT /api/v8/fsms/{fname}

Description
Update the given FSM
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the FSM
  • display_name (*string): the new display name for the FSM; generated from name if necessary
  • short_desc (*string): the short plain-text description for the FSM
  • desc (*string): the new description for the FSM with markdown formatting
  • groups (*list<string>): interface groups that the FSM belongs to
  • input_type (*UndefinedHash): the input type for the FSM
  • output_type (*UndefinedHash): the output type for the FSM
  • states (*UndefinedHash): the state definitions for the FSM
  • options (*UndefinedHash): options for the FSM
  • autovar (*UndefinedHash): automatic variables for the FSM
  • localvar (*UndefinedHash): local variables for the FSM
  • globalvar (*UndefinedHash): global variables for the FSM
Return Value
This API returns a FsmUpdateInfo hash with the following keys (the result of updating the FSM):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such FSM
Note
Requires one of the following permissions:

POST /api/v8/fsms/{fname}?action=clone

Description
Clones the current FSM; all parameters are optional and override the cloned FSM's values. If no name is provided, then a new name is generated for the cloned FSM
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the FSM
  • display_name (*string): the new display name for the FSM; generated from name if necessary
  • short_desc (*string): the short plain-text description for the FSM
  • desc (*string): the new description for the FSM with markdown formatting
  • groups (*list<string>): interface groups that the FSM belongs to
  • input_type (*UndefinedHash): the input type for the FSM
  • output_type (*UndefinedHash): the output type for the FSM
  • states (*UndefinedHash): the state definitions for the FSM
  • options (*UndefinedHash): options for the FSM
  • autovar (*UndefinedHash): automatic variables for the FSM
  • localvar (*UndefinedHash): local variables for the FSM
  • globalvar (*UndefinedHash): global variables for the FSM
Return Value
This API returns a CloneFsmInfo hash with the following keys (a description of the new FSM):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/fsms/{fname}?action=disable

Description
Disables the current FSM, if it is supported by a job (as a scheduled FSM) or a service (as an event-driven FSM)
Arguments
Return Value
This API returns a FsmEnableInfo hash with the following key (hash providing information about the operation):
  • info (string): a string describing the operation
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/fsms/{fname}?action=enable

Description
Enables the current FSM, if it is supported by a job (as a scheduled FSM) or a service (as an event-driven FSM)
Arguments
Return Value
This API returns a FsmEnableInfo hash with the following key (hash providing information about the operation):
  • info (string): a string describing the operation
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/fsms/{fname}?action=exec

Description
Execute the given FSM and return any output
Arguments
This API takes the following hash arguments:
  • input_data (auto): any input data for the FSM
  • state_data (*bool): return information about state data in the response
Return Value
This API returns a FsmExecInfo hash with the following keys (the result of executing the FSM):
  • output_data (auto): any output data for the FSM
  • state_data (FsmStateDataInfo): a hash keyed by state ID where values are the last output data for each state with a sort key
    • sort (int): the sort key to provide order for the hash
    • success (bool): if the state was successfully executed or not
    • response (auto): the output data of the state, if any, and if there was no error
    • error (*string): any uncaught error raised by the state

GET /api/v8/fsms/{fname}?action=file

Description
Returns the Qog as a file that can be saved

PUT /api/v8/fsms/{fname}?action=getStateData

Description
Returns output data for multiple states
Arguments
This API takes the following hash arguments:
  • data_context (*string): the data type for any target field; if present, only compatible fields will be returned
  • current_state (*string): any current state so that only data from previous states will be returned
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): hash of state data keyed by state name
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/fsms/{fname}/config

This REST URI path provides actions and information related to Qorus Finite State Machine configuration items

GET /api/v8/fsms/{fname}/config

Description
Returns a list of Finite State Machine configuration items for the Finite State Machine
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

GET /api/v8/fsms/{fname}/config?action=yaml

Description
Returns a list of configuration items for the Finite State Machine as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/fsms/{fname}/config/{name}

This REST URI path provides actions and information related to a particular configuration item for a particular Qorus Finite State Machine.

Prefixes can be passed within the config item name or as following: /v5/fsms/{name}/config/{name}?prefix={prefix}.

DELETE /api/v8/fsms/{fname}/config/{name}

Description
Permanently deletes the current value for the configuration item for the current Finite State Machine
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/fsms/{fname}/config/{name}

Description
Returns a hash for the current Finite State Machine configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

PUT /api/v8/fsms/{fname}/config/{name}

Description
Sets the value for the given Finite State Machine configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/fsms/{fname}/config/{name}?action=yaml

Description
Sets the value for the given Finite State Machine configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/fsms/{fname}/config/{name}?action=yaml

Description
Returns a hash for the current Finite State Machine configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

DELETE /api/v8/fsms/{fname}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item for this Finite State Machine on the local level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/fsms/{name}

This REST API path provides actions and information related to a particular Qorus Finite State Machine.

GET /api/v8/fsms/{name}

Description
Returns the description of the Finite State Machine

/api/v8/fsms/{name}/config

This REST URI path provides actions and information related to Qorus Finite State Machine configuration items

GET /api/v8/fsms/{name}/config

Description
Returns a list of Finite State Machine configuration items for the Finite State Machine
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

GET /api/v8/fsms/{name}/config?action=yaml

Description
Returns a list of configuration items for the Finite State Machine as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/fsms/{name}/config/{name}

This REST URI path provides actions and information related to a particular configuration item for a particular Qorus Finite State Machine.

Prefixes can be passed within the config item name or as following: /v5/fsms/{name}/config/{name}?prefix={prefix}.

DELETE /api/v8/fsms/{name}/config/{name}

Description
Permanently deletes the current value for the configuration item for the current Finite State Machine
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/fsms/{name}/config/{name}

Description
Returns a hash for the current Finite State Machine configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

PUT /api/v8/fsms/{name}/config/{name}

Description
Sets the value for the given Finite State Machine configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/fsms/{name}/config/{name}?action=yaml

Description
Sets the value for the given Finite State Machine configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/fsms/{name}/config/{name}?action=yaml

Description
Returns a hash for the current Finite State Machine configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "fsm:name1", "fsm:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

DELETE /api/v8/fsms/{name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item for this Finite State Machine on the local level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/functions

This REST API path provides actions and information about Qorus functions

GET /api/v8/functions

Description
Returns a list of hashes of all functions
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of hashes with the following keys (if neither list nor short options are passed as above):
  • name: the name of the function
  • version: the version of the function
  • function_instanceid: the function ID
  • function_type: the type of function object; see Step Function Types for possible values
  • description: the description of the function
  • author: the author of the function
  • created: the date/time the function was created
  • modified: the date/time the function was modified
  • source: the source file that the function object was created from
  • line: the offset in the source file for the source of the function object

POST /api/v8/functions

Description
Creates a new function
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the function
  • desc (*string): the new description for the function with markdown formatting
  • version (string): the new version for the function
  • author (*string): the author of the function
  • source (string): the source code for the function
  • function_type (string): The type of the function
Return Value
This API returns a CreateFunctionInfo hash with the following keys (a description of the new function):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/functions?action=create

Description
Creates a new function
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the function
  • desc (*string): the new description for the function with markdown formatting
  • version (string): the new version for the function
  • author (*string): the author of the function
  • source (string): the source code for the function
  • function_type (string): The type of the function
Return Value
This API returns a CreateFunctionInfo hash with the following keys (a description of the new function):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/functions?action=list

Description
Identical to GET /api/functions
See also
GET /api/functions

/api/v8/functions/{id_or_name}

This REST API path provides actions and information about specific functions

DELETE /api/v8/functions/{id_or_name}

Description
Deletes the function
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a FunctionDeletionInfo hash with the following key (information about the function that was deleted):
  • id (int): the ID of the function that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such function
Note
Requires one of the following permissions:

GET /api/v8/functions/{id_or_name}

Description
Returns a hash of information about the current function
Return Value
This API returns a REST Function Hash

PUT /api/v8/functions/{id_or_name}

Description
Updates the current function
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the function
  • desc (*string): the new description for the function with markdown formatting
  • version (*string): the new version for the function
  • author (*string): the author of the function
  • source (*string): the source code for the function
  • function_type (*string): The type of the function
Return Value
This API returns an UpdateFunctionInfo hash with the following keys (a description of the new function):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/functions/{id_or_name}?action=clone

Description
Clones the current function; all parameters are optional and override the cloned function's values. If no version is provided, then the current version is incremented in the cloned function; if a version but no name is provided, then a new name is generated for the cloned function
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the function
  • desc (*string): the new description for the function with markdown formatting
  • version (*string): the new version for the function
  • author (*string): the author of the function
  • source (*string): the source code for the function
  • function_type (*string): The type of the function
Return Value
This API returns a CloneFunctionInfo hash with the following keys (a description of the new function):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/functions/{id_or_name}?action=file

Description
Returns the function as a file that can be saved

/api/v8/groups

This URI path provides actions and information related to interface groups

DELETE /api/v8/groups

Description
Permanently deletes one or more interface groups. Changes are committed to the database before the call returns.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • groups: (required) list of strings or a single string; a comma-separated string will be split into a list; the names of the groups to delete
Return Value
This API returns a list of string messages giving the result of each delete operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: GROUPS-DELETE-ERROR: missing groups argument
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_DELETE_GROUP
See also

GET /api/v8/groups

Description
Returns a list of hashes of information about interface groups
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); at least one of the following keys must be present:
Return Value
Unless list or short are present, this API returns a list of REST Interface Group Detail Hash elements according to the arguments.
See also

POST /api/v8/groups

Description
Creates a new interface group. If a new group is created with the enabled flag set to False, then workflows, services, and jobs members of the group are stopped immediately if loaded/running. Changes are committed to the database before the call returns.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • group: (string) required; the name of the group
  • desc: (string) required; the description of the group
  • workflows: (list of strings or a single string) optional; a comma-separated string will be split into a list; the list of workflow names or IDs to include in the group
  • services: (list of strings or a single string) optional; a comma-separated string will be split into a list; the list of user service names or IDs to include in the group
  • jobs: (list of strings or a single string) optional; a comma-separated string will be split into a list; the list of job names or IDs to include in the group
  • mappers: (list of strings or a single string) optional; a comma-separated string will be split into a list; the list of mapper names or IDs to include in the group
  • vmaps: (list of strings or a single string) optional; a comma-separated string will be split into a list the list of value map names or IDs to include in the group
  • fsms: (list of strings) optional; a comma-separated string will be split into a list the list of Finite State Machine names to include in the group
  • pipelines: (list of strings) optional; a comma-separated string will be split into a list the list of data pipeline names to include in the group
  • enabled: (string) this value will be processed by parse_boolean(); the initial enabled flag for the group; if not present defaults to True
Return Value
This API returns a REST Interface Group Detail Hash for the new group
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: WORKFLOW-ERROR: invalid or unknown workflow
  • 409 Conflict: SERVICE-ERROR: invalid or unknown service
  • 409 Conflict: JOB-ERROR: invalid or unknown job
  • 409 Conflict: MAPPER-ERROR: invalid or unknown mapper
  • 409 Conflict: VALUE-MAP-ERROR: invalid or unknown value map
  • 409 Conflict: FSM-ERROR: invalid or unknown Finite State Machine
  • 409 Conflict: PIPELINE-ERROR: invalid or unknown data pipeline
  • 409 Conflict: GROUP-ERROR: missing group or desc arguments
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_ADD_GROUP
See also

GET /api/v8/groups?action=list

Description
Returns a list of hashes of information about interface groups
See also
This API is equivalent to GET /api/groups; see that documentation for details.

PUT /api/v8/groups?action=setStatus

Description
Changes the enabled status of one or more interface groups; changes are committed to the database before the call returns
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • groups: (required) one or more group names to modify; a comma-separated string will be split into a list
  • enabled: (required) parsed with Qore::parse_boolean(); the new enabled status for the group(s)
Return Value
This API returns list of descriptive strings for the operations performed
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: GROUPS-SETSTATUS-ERROR: missing groups or enabled arguments
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

/api/v8/groups/{name}

This URI path provides actions and information related to a specific interface group

DELETE /api/v8/groups/{name}

Description
Permanently deletes an interface group; changes are committed to the database before the call returns. When a disabled group is deleted, then any workflows with a positive autostart value, any services with the autostart flag set, and any active jobs are immediately started if the group was previously disabled and the workflow, service, or job is not a member of any other disabled group.
Return Value
This API returns a hash with the following key:
  • info: a string describing the group deletion action
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: cannot update group "DEFAULT"
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_DELETE_GROUP
See also

GET /api/v8/groups/{name}

Description
Returns a hash of information about the current interface group
Return Value
This API returns a REST Interface Group Detail Hash

PUT /api/v8/groups/{name}

Description
Modifies an existing interface group; changes are committed to the database before the call returns. Changes to groups are effected immediately; for example, if a workflow, service, or job is added to a disabled group, the any corresponding running objects are immediately stopped; or if a job is removed from a disabled group, then it is immediately started, etc
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); at least one of the following keys must be present:
  • desc: (string) the new description of the group
  • workflows: (list of strings or a single string) the list of workflow names to include in the group; the new list will replace the current list unless the workflow names are preceded by "+" or "-", meaning add or remove a workflow, respectively (in which case all workflow names must be preceded by a "+" or "-")
  • services: (list of strings or a single string) the list of user service names to include in the group; the new list will replace the current list unless the user service names are preceded by "+" or "-", meaning add or remove a service, respectively (in which case all service names must be preceded by a "+" or "-")
  • jobs: (list of strings or a single string) the list of job names to include in the group; the new list will replace the current list unless the job names are preceded by "+" or "-", meaning add or remove a job, respectively (in which case all job names must be preceded by a "+" or "-")
  • mappers: (list of strings or a single string) the list of mapper names to include in the group; the new list will replace the current list unless the mapper names are preceded by "+" or "-", meaning add or remove a mapper, respectively (in which case all mapper names must be preceded by a "+" or "-")
  • vmaps: (list of strings or a single string) the list of value map names to include in the group; the new list will replace the current list unless the value map names are preceded by "+" or "-", meaning add or remove a value map, respectively (in which case all value map names must be preceded by a "+" or "-")
  • enabled: (string) this value will be processed by parse_boolean(); enables or disables the group
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Conflict: RBAC-UPDATE-GROUP-ERROR: at least one of desc, services, workflows, jobs, mappers, vmaps, or enabled keys must be passed in the second argument hash to update the group
  • 403 Forbidden: cannot update group "DEFAULT"
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

POST /api/v8/groups/{name}?action=clone

Description
Clones the current group
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the group; if not provided, the new name will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the group with markdown formatting
Return Value
This API returns a CloneGroupInfo hash with the following keys (a description of the new group):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/groups/{name}?action=disable

Description
Disables an interace group; changes are committed to the database before the call returns
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: cannot update group "DEFAULT"
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

PUT /api/v8/groups/{name}?action=enable

Description
Enables an interface group; changes are committed to the database before the call returns
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: cannot update group "DEFAULT"
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

PUT /api/v8/groups/{name}?action=setStatus

Description
Changes the enabled status of an interface group; changes are committed to the database before the call returns
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a hash with the following key:
  • info: a string describing the group enabled status change
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: GROUP-SETSTATUS-ERROR: missing enabled argument
Note
requires permission OMQ::QR_GROUP_CONTROL, OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

PUT /api/v8/groups/{name}?action=update

Description
Modifies an existing interface group; changes are committed to the database before the call returns. Changes to groups are effected immediately; for example, if a workflow, service, or job is added to a disabled group, the any corresponding running objects are immediately stopped; or if a job is removed from a disabled group, then it is immediately started, etc
See also
This API is equivalent to PUT /api/groups/{name}; see that documentation for details.

/api/v8/jobresults

This REST API path provides actions and information about job results (job instances).

GET /api/v8/jobresults

Description
Returns a list of hashes of job result (job instance) information corresponding to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: optional (parsed as a date); the past cutoff date for the search; only orders with a modified date equal or after this date will be considered; if not present, then defaults to the last 24 hours
  • desc: optional (parsed with Qore::parse_boolean(); determines the sort order; if False then results are sorted in ascending order, if True (the default), results are sorted in descending order (newest first)
  • full: optional (parsed with Qore::parse_boolean(); if True then additional keys are included in each result record; see below for details
  • ids: optional; one or more job IDs to filter the result list; a comma-separated string will be split into a list
  • limit: optional; limits the number of results returned
  • offset: optional; the starting result to return (use when paging for example)
  • sort: optional; a list of columns to sort the output by
  • statuses: optional; job result (job instance) status value(s); a comma-separated string will be split into a list (see Job Data Status Descriptions for possible values)
Return Value
This API returns a list of REST Job Result Hash elements corresponding to the arguments; if the full option is set, then the following additional keys are included in each hash:
  • errors: a list of hashes of errors and warnings raised by the job; each list element has the following keys:
    • job_errorid: the unique ID for the error instance
    • severity: an error severity code (see Error Severity Codes for possible values)
    • error: the error code string
    • description: description for the error (if any)
    • info: additional information about the error (if any)
    • business_error: a boolean flag indicating of the error is a business error
    • created: the date and time the error was raised
  • audit: a list of one or more REST Audit Info Hash elements (can be empty)

GET /api/v8/jobresults?action=overview

Description
Returns aggregate job result information corresponding to the arguments.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: optional (parsed as a date); the past cutoff date for the search; only orders with a modified date equal or after this date will be considered; if not present, then defaults to the last 24 hours
  • sqlcache: optional (parsed with Qore::parse_boolean()); if False then no SQL cache will be used for historical info; default True
  • combined: if True then all results are combined into one global hash for all queried jobs
  • jobs: one or more job names or IDs to filter the result list; a comma-separated string will be split into a list
Return Value
This API returns a hash keyed by job name; values are hashes keyed by job status value (see Job Data Status Descriptions for possible values) and the values are integer job result (job instance) counts having the given status (unless combined is set, described above)
Example Return Value
myjob_1 : hash: (2 members)
  ERROR : 1
  COMPLETE : 3
myjob_2 : hash: (2 members)
  IN-PROGRESS : 1
  COMPLETE : 8

/api/v8/jobresults/{id}

This REST API path provides actions and information about specific job results (job instances).

GET /api/v8/jobresults/{id}

Description
Returns a hash of job result (job instance) information
Return Value
This API returns a REST Job Result Hash with the following additional keys:
  • errors: a list of hashes of errors and warnings raised by the job; each list element has the following keys:
    • job_errorid: the unique ID for the error instance
    • severity: an error severity code (see Error Severity Codes for possible values)
    • error: the error code string
    • description: description for the error (if any)
    • info: additional information about the error (if any)
    • business_error: a boolean flag indicating of the error is a business error
    • created: the date and time the error was raised
  • audit: a list of one or more REST Audit Info Hash elements (can be empty)

/api/v8/jobs

This REST API path provides actions and information related to Qorus jobs.

GET /api/v8/jobs

Description
Returns information about Qorus jobs according to the arguments; only jobs accessible to the calling user are returned
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • defonly: optional (parsed with Qore::parse_boolean()); if True then no job result information will be included in the return value; default False
  • date: optional (parsed as a date); the past cutoff date for job result (job instances) for the return value; if not present, then defaults to the last 24 hours
  • jobs: one or more job names or IDs to filter the result list; a comma-separated string will be split into a list
  • lib_source: optional; parsed with Qore::parse_boolean(); if True then the source code for each library object is returned in the REST Job Description Hash
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of job names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings of job names and descriptions is returned
  • sqlcache: optional (parsed with Qore::parse_boolean()); if False then no SQL cache will be used for historical info; default True (only used if defonly is omitted or False)
  • status: optional; either "active" or "inactive" to filter jobs based on their active status
  • tags: optional; a hash of tags to match; only workflows matching at least one of the tags will be returned; use tag=value format as the value of this option
  • tag_case_insensitive: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons are made with case-insensitive comparisons
  • tag_partial_match: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons succeed if the value given as the tag value appears anywhere in the object's tag of the same name
Return Value
If neither list nor short are used, then this API returns a list of REST Job Description Hash elements; if defonly is not True, then any jobs with job result data within the given time period (as defined by the date option) will be reflected in the following extra keys:
  • IN-PROGRESS: the number of job instances currently in progress
  • COMPLETE: the number of job instances with a OMQ::StatComplete status during the given time period
  • ERROR: the number of job instances with a OMQ::StatError status during the given time period

POST /api/v8/jobs

Description
Creates a new job
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the job
  • version (string): the version of the job
  • display_name (*string): the new display name for the job; generated from name if necessary
  • short_desc (*string): the short plain-text description for the job
  • desc (string): the new description for the job with markdown formatting
  • schedule (JobCronHash): the cron schedule for the job
  • author (*list<string>): one or more authors of the job
  • remote (*bool): if the job should run remotely or not
  • active (*bool): if the job is active (will be scheduled) or not
  • enabled (*bool): if the job is enabled
  • expiry-date (*date): the date the job expires
  • class-name (*string): the class name fot the job
  • lang (*string): the language of the job
  • classes (*list<string>): classes that the job depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the job uses
  • mappers (*list<string>): mappers that the job uses
  • vmaps (*list<string>): value maps that the job uses
  • groups (*list<string>): interface groups that the job belongs to
  • tags (*UndefinedHash): user-defined tags for the job
  • config-items (*list<UndefinedHash>): config items that the job uses or defines
  • system-options (UndefinedHash): system options for the job
  • source (string): the job's source code
Return Value
This API returns a CreateJobInfo hash with the following keys (a description of the new job):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/jobs?action=create

Description
Creates a new job
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the job
  • version (string): the version of the job
  • display_name (*string): the new display name for the job; generated from name if necessary
  • short_desc (*string): the short plain-text description for the job
  • desc (string): the new description for the job with markdown formatting
  • schedule (JobCronHash): the cron schedule for the job
  • author (*list<string>): one or more authors of the job
  • remote (*bool): if the job should run remotely or not
  • active (*bool): if the job is active (will be scheduled) or not
  • enabled (*bool): if the job is enabled
  • expiry-date (*date): the date the job expires
  • class-name (*string): the class name fot the job
  • lang (*string): the language of the job
  • classes (*list<string>): classes that the job depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the job uses
  • mappers (*list<string>): mappers that the job uses
  • vmaps (*list<string>): value maps that the job uses
  • groups (*list<string>): interface groups that the job belongs to
  • tags (*UndefinedHash): user-defined tags for the job
  • config-items (*list<UndefinedHash>): config items that the job uses or defines
  • system-options (UndefinedHash): system options for the job
  • source (string): the job's source code
Return Value
This API returns a CreateJobInfo hash with the following keys (a description of the new job):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

DELETE /api/v8/jobs?action=defaultLogger

Description
Delete logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/jobs?action=defaultLogger

Description
Set logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/jobs?action=defaultLogger

Description
Create default Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/jobs?action=defaultLogger

Description
Returns default logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services). If set means default logger

PUT /api/v8/jobs?action=defaultLoggerAppenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/jobs?action=defaultLoggerAppenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/jobs?action=defaultLoggerAppenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/jobs?action=defaultLoggerAppenders

Description
Return all logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

PUT /api/v8/jobs?action=disable

Description
Disables one or more jobs.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more job names or IDs to disable; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • arg: the job ID or name (the argument passed as input)
  • disabled: True means the job was disabled, False means it was not
  • info: an informative string giving a description of the result or an error message
  • [jobid]: the job ID
  • [name]: the name of the job
  • [version]: the version of the job
Errors
  • 409 Conflict: JOB-DISABLE-ERROR: missing ids argument
See also

PUT /api/v8/jobs?action=enable

Description
Enables one or more disabled jobs.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more job names or IDs to enable; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • arg: the job ID or name (the argument passed as input)
  • enabled: True means the job was enabled, False means it was not
  • info: an informative string giving a description of the result or an error message
  • [jobid]: the job ID
  • [name]: the name of the job
  • [version]: the version of the job
Errors
  • 409 Conflict: JOB-ENABLE-ERROR: missing ids argument
Note
requires permission OMQ::QR_JOB_CONTROL, OMQ::QR_GROUP_CONTROL, or OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

GET /api/v8/jobs?action=list

Description
Returns information about Qorus jobs according to the arguments; only jobs accessible to the calling user are returned
See also
This API is equivalent to GET /api/jobs; see that documentation for details.

PUT /api/v8/jobs?action=reset

Description
Reloads one or more jobs from the database; if the job is currently running it is stopped and reloaded. This API works on all jobs regardless of state; the job does not have to be running or active to be reset.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more job names or IDs to reset; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes with the following keys:
  • arg: the job ID or name (the argument passed as input)
  • reset: True means the job was reset, False means it was not
  • info: an informative string giving a description of the result or an error message
  • [jobid]: the job ID
  • [name]: the name of the job
  • [version]: the version of the job
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESET_JOB
See also

PUT /api/v8/jobs?action=run

Description
Runs one or more jobs and returns the results of job execution
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more job names or IDs to run; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes with the following keys:
  • arg: the job ID or name (the argument passed as input)
  • run: True means the job was run, False means it was not
  • info: an informative string giving a description of the result or an error message
  • [jobid]: the job ID
  • [name]: the name of the job
  • [version]: the version of the job
  • [job_instanceid]: the job_instanceid of the job executed
  • [status]: the status of the execution of the job; see Job Data Status Descriptions for possible values
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RUN_JOB
See also

/api/v8/jobs/{id_or_name}

This REST API path provides actions and information related to specific jobs; the name can also be provided in the format name:version.

DELETE /api/v8/jobs/{id_or_name}

Description
Deletes the current job
Arguments
Return Value
This API returns a JobDeletionResult hash with the following keys (job deletion info):
  • name (string): the name of the job deleted
  • jobid (string): the ID of the job deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such job
Note
Requires one of the following permissions:

GET /api/v8/jobs/{id_or_name}

Description
Returns a hash of information about the current job
Arguments
Return Value
This API returns a JobDetailInfo hash with the following keys (a hash of information about the current job):
  • name (string): the name of the job
  • jobid (int): the job ID
  • display_name (*string): the display name
  • short_desc (*string): the short description in plain text
  • description (*string): the description of the job (if any)
  • version (string): the version of the job
  • author (*string): the author of the job (if any)
  • sessionid (*int): If the job is currently active and running on a Qorus instance, then this attribute will have a value, otherwise it will not be set
  • remote (bool): the remote state of the job; if True, the job will run remotely in a qjob process; if False, it will run in qorus-core
  • manual_remote (bool): set if the manual value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • open (bool): if the current workflow is open for processing now
  • run_skipped (bool): A boolean value telling the system if the job should be run immediately if the last scheduled run was missed due to system downtime
  • enabled (bool): flag indicating if the job is enabled or not; disabled jobs cannot be activated
  • code (string): the source code for the job
  • class_based (bool): True means that the job is an extension of the QorusJob class, otherwise it is a function-based job
  • class_name (*string): the name of the job class, if any
  • language (string): the programming language that the job's main code is implemented in
  • month (*string): the month value in a job cron schedule
  • day (*string): the day value in a job cron schedule
  • wday (*string): the weekday value in a job cron schedule
  • hour (*string): the hout value in a job cron schedule
  • minute (*string): the minute value in a job cron schedule
  • expiry_date (*date): the expiry date of the job, if any
  • last_executed (*date): the date-time value the job was last executed, if any
  • last_executed_job_instanceid (*int): the last job instance ID, if any
  • last_jobstatus (*string): the last job result status for this job
  • manually_updated (bool): flag set if the job schedule has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • created (date): the date/time the job was created
  • modified (date): the date/time the job was modified
  • source (*string): the complete path of the job source file when loaded
  • line (*int): the line offset of the job source code in the file
  • config_items (*list<ConfigItemDetailInfo>): list of config items attached directly to the job
  • fsm_triggers (*FsmTriggerSet): a hash keyed by finite state machine name giving triggers for each flow
    • key (list<FsmTriggerInfo>): list<FsmTriggerInfo> value
  • next (*date): the next automatic job execution time time, if any
  • schedule (*string): the schedule for the job as a string
  • mappers (*list<MapperInfo>): list of mappers associated with the job
  • vmaps (*list<VMapInfo>): a list of value maps associated with the job
  • lib (*LibraryInfo): a hash of library information for the job
    • functions (*list<LibraryDetailInfo>): a list of function objects (can be empty)
    • classes (*list<LibraryDetailInfo>): a list of class objects (can be empty)
    • constants (*list<LibraryDetailInfo>): a list of constant objects (can be empty)
    • pipelines (*list<NameIdInfo>): a list of pipeline objects (can be empty)
    • fsm (*list<NameIdInfo>): a list of FSM objects (can be empty)
  • tags (*UndefinedHash): any tags for the job
  • job_modules (*list<string>): a list of job modules associated with the job
  • config (*ConfigItemSummarySetInfo): a hash of configuration item info keyed by config item name
    • name (string): the name of the configuration item
    • prefix (*string): the prefix of the configuration item
    • type (string): the data type of the configuration item
    • desc (string): the description of the configuration item
    • default_value (auto): the default value of the configuration item
    • value (auto): the value of the configuration item
    • strictly_local (bool): if the configuration item is defined strictly on local level
    • is_set (bool): True if the value is set otherwise False
    • is_templated_string (bool): True if the value is a templated string that can be later expanded
    • config_group (string): the group of the configuration item
    • allowed_values (*list<auto>): the list of allowed values for the configuration item if defined
    • level (string): the level from where the value is obtained (interface level (e.g. "job:1", "job:2")
  • groups (*list<GroupInfo>): a list of interface groups that the job belongs to
  • offset (*string): the line offset of the job source code in the file
  • host (*string): the hostname of the machine where the job was loaded from
  • user (*string): the OS user who loaded the job
  • base_class_name (*string): the base class name of the job, if any
  • process (*JobProcessExecInfo): present when remote is True
    • id (string): the unique process ID in the cluster
    • node (string): the node name where the process is running
    • host (string): the hostname where the process is running
    • pid (int): the PID on the host
    • urls (list<string>): a list of ZeroMQ URLs for the process
    • status (*int): the process's status code
    • status_string (*string): the process's status as a string
    • restarted (*bool): indicates if the process has been restarted
    • log_pipe (*string): any log pipe for the process
    • port (*int): any port number for the process
    • priv (*int): the amount of private memory of the process in bytes
    • prometheus_port (*int): any port number for communicating with Prometheus
    • rss (*int): the resident size of the process in bytes
    • vsz (*int): the virtual size of the process in bytes
    • priv_str (*string): a string description of the priv value
    • pct (*int): the percentage of main memory taken up by the process on the node
    • jobname (*string): the job name
    • jobversion (*string): the job version
    • jobid (*int): the job ID
    • socket_path (*string): any socket path for the process
    • sessionid (*int): the job session ID
  • COMPLETE (*int): number of job results with status COMPLETE
  • IN-PROGRESS (*int): number of job results with status IN-PROGRESS
  • ERROR (*int): number of job results with status ERROR
  • CRASH (*int): number of job results with status CRASH
  • connections (*list<InterfaceConnectionInfo>): a list of connection objects that this job depends on
  • alerts (*list<AlertInfo>): a list of alerts raised against the job
  • db_active (bool): a boolean flag indicating the active status in the database
  • active (bool): the active status in the current Qorus instance
  • manual_active (bool): set if the active value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • log_url (*string): the log URL (if any)
  • options (list<OptionInfoHash>): a list option information hashes
  • sched_type (string): the schedule type; one of "cron" (uses a job cron schedule), or "recurring" ( uses a fixed repeat delay)
  • sched_txt (string): a string describing the schedule (ex: "minutes: 0, hours: 0, days: *, months: *, wdays: *")
  • sla (*string): the name of the attached SLA, if any)
  • state (*hash<auto>): any job state data
  • persistent-state (*hash<auto>): any persistent job state data
Errors
  • 403 Forbidden: access or authorization error

PUT /api/v8/jobs/{id_or_name}

Description
Updates the current job
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the job
  • version (*string): the version of the job
  • display_name (*string): the new display name for the job; generated from name if necessary
  • short_desc (*string): the short plain-text description for the job
  • desc (*string): the new description for the job with markdown formatting
  • schedule (*JobCronHash): the cron schedule for the job
  • author (*list<string>): one or more authors of the job
  • remote (*bool): if the job should run remotely or not
  • active (*bool): if the job is active (will be scheduled) or not
  • enabled (*bool): if the job is enabled
  • expiry-date (*date): the date the job expires
  • class-name (*string): the class name fot the job
  • lang (*string): the language of the job
  • classes (*list<string>): classes that the job depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the job uses
  • mappers (*list<string>): mappers that the job uses
  • vmaps (*list<string>): value maps that the job uses
  • groups (*list<string>): interface groups that the job belongs to
  • tags (*UndefinedHash): user-defined tags for the job
  • config-items (*list<UndefinedHash>): config items that the job uses or defines
  • system-options (*UndefinedHash): system options for the job
  • source (*string): the job's source code
Return Value
This API returns an UpdateJobInfo hash with the following keys (a description of the new job):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/jobs/{id_or_name}?action=clone

Description
Clones the current job; all parameters are optional and override the cloned job's values. If no name is provided, then a new name is generated for the cloned job
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the job
  • version (*string): the version of the job
  • display_name (*string): the new display name for the job; generated from name if necessary
  • short_desc (*string): the short plain-text description for the job
  • desc (*string): the new description for the job with markdown formatting
  • schedule (*JobCronHash): the cron schedule for the job
  • author (*list<string>): one or more authors of the job
  • remote (*bool): if the job should run remotely or not
  • active (*bool): if the job is active (will be scheduled) or not
  • enabled (*bool): if the job is enabled
  • expiry-date (*date): the date the job expires
  • class-name (*string): the class name fot the job
  • lang (*string): the language of the job
  • classes (*list<string>): classes that the job depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the job uses
  • mappers (*list<string>): mappers that the job uses
  • vmaps (*list<string>): value maps that the job uses
  • groups (*list<string>): interface groups that the job belongs to
  • tags (*UndefinedHash): user-defined tags for the job
  • config-items (*list<UndefinedHash>): config items that the job uses or defines
  • system-options (*UndefinedHash): system options for the job
  • source (*string): the job's source code
Return Value
This API returns a CloneJobInfo hash with the following keys (a description of the new job):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=disable

Description
Disables the current job if it is enabled; if the job is already disabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a JobUpdateResultInfo hash with the following keys (information about the result of the operation):
  • jobid (int): the workflow ID
  • name (string): the wojobrkflow name
  • version (string): the job version
  • info (string): a string providing information about the job update action
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=enable

Description
Enables the current job if it is disabled; if the job is already enabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a JobUpdateResultInfo hash with the following keys (information about the result of the operation):
  • jobid (int): the workflow ID
  • name (string): the wojobrkflow name
  • version (string): the job version
  • info (string): a string providing information about the job update action
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

GET /api/v8/jobs/{id_or_name}?action=file

Description
Returns the job as a file that can be saved

POST /api/v8/jobs/{id_or_name}?action=kill

Description
Kills a remote job cluster process
Arguments
Return Value
This API returns a KillResultInfo hash with the following keys (information about the result of the operation):
  • status (string): either "OK" or "ERR"
  • code (int): the return code of the kill() command: 0 if successful, non-zero if not
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: if no remote process is running for the job
Note
Requires one of the following permissions:

GET /api/v8/jobs/{id_or_name}?action=options

Description
Returns options set on the current job.
Return Value
This API returns NOTHING if no options are set, otherwise a hash of job options.

PUT /api/v8/jobs/{id_or_name}?action=reset

Description
Resets and reloads the current job by reloading its configuration in the metadata cache; if the job is currently running, then the reset will cause the job configuration to be reset as soon as it completes its current run.
Arguments
Return Value
This API returns a value of type string: a descriptive string for the operation
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: API-CALL-ERROR: cannot reset a disabled job
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=run

Description
Runs a job and returns the results of job execution
Arguments
Return Value
This API returns a JobExecResultInfo hash with the following keys (the result of job execution):
  • job_instanceid (int): the job_instanceid
  • status (string): the status of the execution of the job; see Job Data Status Descriptions for possible values
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=schedule

Description
Updates the schedule of a job; if any errors occur an exception is thrown. This API works on all jobs regardless of state; the job does not have to be running or active to be updated.
Arguments
This API takes the following hash arguments:
  • schedule (*string): a cron-like string giving the job schedule, see job schedule for information about the format; either this parameter or duration must be present, but not both
  • duration (*int): a duration in seconds for triggering the job; either this parameter or schedule must be present, but not both; the duration must be less than 10^7.
Return Value
This API returns a JobScheduleUpdateInfo hash with the following keys (a hash of information about the update operation):
  • jobid (int): the job ID
  • name (string): the job name
  • schedule (*string): the new schedule for the job
  • duration (*int): the new dduration for the job
  • info (string): a descriptive string
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=setActive

Description
Updates the active status of a job; if any errors occur an exception is thrown.
Arguments
This API takes the following hash argument:
  • active (bool): the new active state of the job
Return Value
This API returns a JobActiveUpdateInfo hash with the following keys (a hash of information about the update operation):
  • jobid (int): the job ID
  • name (string): the job name
  • active (bool): the new active state of the job
  • info (string): a descriptive string
  • db_active (bool): the active state in the DB (can differ from active if the job cannot be started for example)
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: JOB-ERROR: cannot set expired jobs to active
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=setExpire

Description
Identical to PUT /api/jobs/{id_or_name}?action=setExpiry

PUT /api/v8/jobs/{id_or_name}?action=setExpiry

Description
Updates the expiry date of a job; if any errors occur an exception is thrown. This API works on all jobs regardless of state; the job does not have to be running or active to be updated. Removing the expiry date or setting a future expiry date from a job that is not started because it has expired will result in the job starting immediately (unless the job is inactive or a member of a disabled group. Setting a past expiry date on a currently-active job will stop the job immediately.
Arguments
This API takes the following hash argument:
  • date (*date): the new expiry date of the job; if not present any expiry date will be removed
Return Value
This API returns a JobExpiryUpdateInfo hash with the following keys (a hash of information about the update operation):
  • jobid (int): the job ID
  • name (string): the job name
  • expiry_date (*date): the new expiry date of the job
  • info (string): a descriptive string
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=setOptions

Description
Sets options for the current job. If the job has an option list and any of the options are not valid for that job, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options to set against the job; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given job (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: JOB-OPTION-ERROR: invalid option for job or option cannot be overridden at the job level
Note

PUT /api/v8/jobs/{id_or_name}?action=setPersistentStateData

Description
Provides an API for externally updating persistent job state data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • data: a hash of new persistent job state data or NOTHING which will clear any data
Return Value
This API returns the new data or NOTHING if the data is cleared
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL
See also

PUT /api/v8/jobs/{id_or_name}?action=setRemote

Description
Updates the remote status of a job, determining if a job runs in a remote process or not. Jobs that have their remote value changed are temporarily disabled and then reenabled after the change.
Arguments
This API takes the following hash argument:
  • remote (bool): the new remote state of the job
Return Value
This API returns a JobRemoteUpdateInfo hash with the following keys (a hash of information about the update operation):
  • updated (bool): if the remote status was updated
  • remote (bool): the new remote state of the job
  • info (string): a descriptive string
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/jobs/{id_or_name}?action=setStateData

Description
Provides an API for externally updating job state data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • data: a hash of new job state data or NOTHING which will clear any data
Return Value
This API returns the new data or NOTHING if the data is cleared
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
Note
requires permission OMQ::QR_JOB_CONTROL
See also
  • job_get_state_data()
  • job_save_state_data()

/api/v8/jobs/{id_or_name}/config

This REST URI path provides actions and information related to Qorus job configuration items

GET /api/v8/jobs/{id_or_name}/config

Description
Returns a list of job configuration items for the job
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "job:1", "job:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given job (for more information, see Interface Groups)

GET /api/v8/jobs/{id_or_name}/config?action=yaml

Description
Returns a list of job configuration items for the job as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "job:1", "job:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given job (for more information, see Interface Groups)

/api/v8/jobs/{id_or_name}/config/{name}

This REST URI path provides actions and information related to a particular Qorus job. Prefix can be passed within the config item name or as following: /v3/jobs/{id_or_name}/config/{name}?prefix={prefix}.

job configuration item

DELETE /api/v8/jobs/{id_or_name}/config/{name}

Description
Permanently deletes the current value for the configuration item on this job level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/jobs/{id_or_name}/config/{name}

Description
Returns a hash for the current job configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "job:1", "job:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given job (for more information, see Interface Groups)

PUT /api/v8/jobs/{id_or_name}/config/{name}

Description
Sets the value for the given job configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

PUT /api/v8/jobs/{id_or_name}/config/{name}?action=yaml

Description
Sets the value for the given job configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

GET /api/v8/jobs/{id_or_name}/config/{name}?action=yaml

Description
Returns a hash for the current job configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "job:1", "job:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: JOB-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given job (for more information, see Interface Groups)

DELETE /api/v8/jobs/{id_or_name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on this job level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/jobs/{id_or_name}/results

This REST API path provides actions and information related to the results of specific jobs.

GET /api/v8/jobs/{id_or_name}/results

Description
Returns a list of hashes of job result (job instance) information for the current job corresponding to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: optional (parsed as a date); the past cutoff date for the search; only orders with a modified date equal or after this date will be considered; if not present, then defaults to the last 24 hours
  • desc: optional (parsed with Qore::parse_boolean(); determines the sort order; if False then results are sorted in ascending order, if True (the default), results are sorted in descending order (newest first)
  • full: optional (parsed with Qore::parse_boolean(); if True then additional keys are included in each result record; see below for details
  • ids: optional; one or more job instance IDs to filter the result list; a comma-separated string will be split into a list
  • limit: optional; limits the number of results returned
  • offset: optional; the starting result to return (use when paging for example)
  • sort: optional; a list of columns to sort the output by
  • statuses: optional; job result (job instance) status value(s); a comma-separated string will be split into a list (see Job Data Status Descriptions for possible values)
Return Value
This API returns a list of REST Job Result Hash elements corresponding to the arguments; if the full option is set, then the following additional keys are included in each hash:
  • errors: a list of hashes of errors and warnings raised by the job; each list element has the following keys:
    • job_errorid: the unique ID for the error instance
    • severity: an error severity code (see Error Severity Codes for possible values)
    • error: the error code string
    • description: description for the error (if any)
    • info: additional information about the error (if any)
    • business_error: a boolean flag indicating of the error is a business error
    • created: the date and time the error was raised
  • audit: a list of one or more REST Audit Info Hash elements (can be empty)

GET /api/v8/jobs/{id_or_name}/results?action=overview

Description
Returns aggregate job result information for the current job corresponding to the arguments.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: optional (parsed as a date); the past cutoff date for the search; only orders with a modified date equal or after this date will be considered; if not present, then defaults to the last 24 hours
  • sqlcache: optional (parsed with Qore::parse_boolean()); if False then no SQL cache will be used for historical info; default True
  • combined: if True then all results are combined into one global hash for all queried jobs
Return Value
This API returns a hash keyed by job name; values are hashes keyed by job status value (see Job Data Status Descriptions for possible values) and the values are integer job result (job instance) counts having the given status (unless combined is set, described above)
Example Return Value
myjob_1 : hash: (2 members)
  ERROR : 1
  COMPLETE : 3
myjob_2 : hash: (2 members)
  IN-PROGRESS : 1
  COMPLETE : 8

/api/v8/logout

This REST API path provides the logout action

POST /api/v8/logout

Description
Removes the token of the current session.
Arguments
None
Return Value
None

/api/v8/logs

This REST URI path provides actions and information related to Qorus system logs and websocket log sources

GET /api/v8/logs

Description
Returns a list of hashes of system log file and websocket URL information
Return Value
This API returns a list of hashes with the following keys:
  • type: one of the following values:
    • "qorus-core": the main system log file
    • "audit": the system audit log file
    • "http": the HTTP log file
    • "mon": the system monitoring log file
    • "alert": the system alert log file
    • "workflow": a workflow log file
    • "service": a service log file
    • "job": a job log file
    • "qdsp": a qdsp process log file
  • log: the log file path on the host filesystem
  • log_url: the websocket log URL for the log file
  • [name]: (for workflows, services, and jobs) the name of the interface
  • [version]: (for workflows, services, and jobs) the version of the interface
  • [workflowid]: (for workflows) the ID of the workflow
  • [serviceid]: (for services) the ID of the service
  • [jobid]: (for jobs) the ID of the job
  • [servicetype]: (for services) the type of the service ("system" or "user")

GET /api/v8/logs?action=list

Description
Returns a list of hashes of system log file and websocket URL information
See also
This API is equivalent to GET /api/logs; see that documentation for details.

/api/v8/mappers

This URI path provides actions and information related to system mappers

GET /api/v8/mappers

Description
Returns a list of hashes describing all accessible system mappers
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Mapper Description Hash elements; if the full option is used, then each hash has the following additional keys:
  • option_source: a hash of the source for the "options" key
  • field_source: a hash of the source for the actual mapper logic itself; keys are output field names

POST /api/v8/mappers

Description
Creates a new mapper
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the mapper
  • display_name (*string): the new display name for the mapper; generated from name if necessary
  • short_desc (*string): the short plain-text description for the mapper
  • desc (string): the new description for the mapper with markdown formatting
  • options (*UndefinedHash): options for the mapper
Return Value
This API returns a CreateMapperInfo hash with the following keys (a description of the new mapper):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/mappers?action=create

Description
Creates a new mapper
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the mapper
  • display_name (*string): the new display name for the mapper; generated from name if necessary
  • short_desc (*string): the short plain-text description for the mapper
  • desc (string): the new description for the mapper with markdown formatting
  • options (*UndefinedHash): options for the mapper
Return Value
This API returns a CreateMapperInfo hash with the following keys (a description of the new mapper):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/mappers?action=reload

Description
Reloads the mappers given in the ids argument from the DB
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) a comma-separated string will be split into a list; the mapper names or IDs to reset
Return Value
This API returns a list of the mapper IDs reset
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: MAPPER-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given mapper (for more information, see Interface Groups)
  • 409 Conflict: MAPPER-ERROR: invalid or unknown mapper
Note
requires permission OMQ::QR_MAPPER_CONTROL or OMQ::QR_RELOAD_MAPPER
See also
PUT /api/mappers?action=reloadAll

PUT /api/v8/mappers?action=reloadAll

Description
Reloads all accessible system mappers
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: MAPPER-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given mapper (for more information, see Interface Groups)
Note
requires permission OMQ::QR_MAPPER_CONTROL or OMQ::QR_RELOAD_MAPPER
See also
PUT /api/mappers?action=reload

/api/v8/mappers/{id_or_name}

This URI path provides actions and information related to a specific system mapper

DELETE /api/v8/mappers/{id_or_name}

Description
Deletes the current mapper
Arguments
Return Value
This API returns a PipelineDeletionResult hash with the following keys (mapper deletion info):
  • name (string): the name of the mapper deleted
  • pipelineid (string): the ID of the data pipeline deleted
  • mapperid (string): the ID of the mapper deleted
  • version (string): the version of the mapper deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such mapper
Note
Requires one of the following permissions:

GET /api/v8/mappers/{id_or_name}

Description
Returns a hash describing the current system mapper
Return Value
This API returns a REST Mapper Description Hash with the following additional keys:
  • option_source: a hash of the source for the "options" key
  • field_source: a hash of the source for the actual mapper logic itself; keys are output field names
Errors
  • 409 Conflict: MAPPER-ERROR: invalid or unknown mapper
  • 403 Forbidden: MAPPER-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given mapper (for more information, see Interface Groups)

PUT /api/v8/mappers/{id_or_name}

Description
Updates the current Mapper
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the mapper
  • display_name (*string): the new display name for the mapper; generated from name if necessary
  • short_desc (*string): the short plain-text description for the mapper
  • desc (*string): the new description for the mapper with markdown formatting
  • options (*UndefinedHash): options for the mapper
Return Value
This API returns an UpdateMapperInfo hash with the following keys (a description of the new mapper):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/mappers/{id_or_name}?action=clone

Description
Clones the current mapper; all parameters are optional and override the cloned mapper's values. If no name is provided, then a new name is generated for the cloned mapper
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the mapper
  • display_name (*string): the new display name for the mapper; generated from name if necessary
  • short_desc (*string): the short plain-text description for the mapper
  • desc (*string): the new description for the mapper with markdown formatting
  • options (*UndefinedHash): options for the mapper
Return Value
This API returns a CloneMapperInfo hash with the following keys (a description of the new mapper):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/mappers/{id_or_name}?action=file

Description
Returns the mapper as a file that can be saved

PUT /api/v8/mappers/{id_or_name}?action=reload

Description
Reloads the current mapper from the DB
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: MAPPER-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given mapper (for more information, see Interface Groups)
Note
requires permission OMQ::QR_MAPPER_CONTROL or OMQ::QR_RELOAD_MAPPER

/api/v8/mappertypes

This REST URI path provides actions and information related to all mapper types

See also
qorus.mapper-modules

GET /api/v8/mappertypes

Description
Returns a list of hashes describing the system mapper types
Return Value
This API returns a list of REST Mapper Type Description Hash elements

/api/v8/mappertypes/{name}

This REST URI path provides actions and information related to a specific mapper type

See also
qorus.mapper-modules

GET /api/v8/mappertypes/{name}

Description
Returns a hash describing the current system mapper type
Return Value
This API returns a REST Mapper Type Description Hash

/api/v8/oauth2

This REST URI path is the root path for OAuth2 admin functionality

/api/v8/oauth2/clients

This REST URI path provides actions and information about OAuth2 clients

GET /api/v8/oauth2/clients

Description
Returns information about OAuth2 clients registered in Qorus
Arguments
This API takes the following hash argument:
  • username (*string): user associated with the clients; can only be specified if the calling user has the USER-CONTROL permission, otherwise the current user is assumed
Return Value
This API returns an OAuth2ClientResponse hash with the following keys (information about client profiles):
  • client_id (string): unique identifier of the client
  • client_description (string): the description for the client
  • username (string): user associated with the client
  • permissions (*list<string>): permissions associated to the client; corresponds to OAuth2 scopes
  • created (date): record creation timestamp
  • modified (date): record last modification timestamp
Errors
  • 400 Bad Request: invalid arguments to method

POST /api/v8/oauth2/clients

Description
Creates an OAuth2 client profile in Qorus; note that the client_secret value returned cannot be retrieved after this call; it must be stored carefully by the user
Arguments
This API takes the following hash arguments:
  • username (*string): user associated with the client; can only be specified if the calling user has the USER-CONTROL permission, otherwise the current user is assumed
  • client_description (string): the description for the OAuth2 client
  • permissions (list<string>): list of permissions; corresponds to OAuth2 scopes
Return Value
This API returns an OAuth2ClientCreationResponse hash with the following key (information about the client profile created):
  • inserted (OAuth2ClientInsertedInfo): hash with informataion about inserted client
    • client_id (string): unique identifier of the client
    • client_description (string): the description for the client
    • client_secret (string): client secret; this value must be stored as it cannot be retrieved after this call
    • username (string): user associated with the client
    • permissions (*list<string>): permissions associated to the client
    • created (date): record creation timestamp
    • modified (date): record last modification timestamp
Errors
  • 400 Bad Request: invalid arguments to method

/api/v8/oauth2/clients/{id}

This REST URI path provides actions and information for system functionality

DELETE /api/v8/oauth2/clients/{id}

Description
Deletes the given OAuth2 client profile
Arguments
Return Value
This API returns an OAuth2ClientDeletionResult hash with the following key (OAuth2 client deletion info):
  • deleted (string): the client ID deleted
Errors
  • 404 Not Found: no such client

GET /api/v8/oauth2/clients/{id}

Description
Returns a hash of client information
Arguments
Return Value
This API returns an OAuth2ClientInfo hash with the following keys (OAuth2 client info):
  • client_id (string): unique identifier of the client
  • client_description (string): the description for the client
  • username (string): user associated with the client
  • permissions (*list<string>): permissions associated to the client; corresponds to OAuth2 scopes
  • created (date): record creation timestamp
  • modified (date): record last modification timestamp
Errors
  • 404 Not Found: no such client

PUT /api/v8/oauth2/clients/{id}

Description
Updates the info for the given OAuth2 client
Arguments
This API takes the following hash arguments:
  • username (string): user associated with the client
  • permissions (list<string>): list of permissions
Return Value
This API returns an OAuth2ClientUpdateResponse hash with the following key (OAuth2 client update info):
  • updated (OAuth2ClientInfo): updated client information
    • client_id (string): unique identifier of the client
    • client_description (string): the description for the client
    • username (string): user associated with the client
    • permissions (*list<string>): permissions associated to the client; corresponds to OAuth2 scopes
    • created (date): record creation timestamp
    • modified (date): record last modification timestamp
Errors
  • 404 Not Found: no such client, invalid arguments to API

POST /api/v8/oauth2/clients/{id}?action=generateSecret

Description
Generates a new client secret for the OAuth2 connection; note that the client_secret value returned cannot be retrieved after this call; it must be stored carefully by the user
Arguments
Return Value
This API returns an OAuth2SecretInfo hash with the following keys (a hash with the new client secret):
  • client_id (string): the client ID of the OAuth2 client
  • client_secret (string): the new client secret for the OAuth2 client; this value must be stored as it cannot be retrieved after this call
Errors
  • 404 Not Found: no such client

/api/v8/oauth2/clients/{id}/tokens

This REST URI path provides actions and information related to OAuth2 client tokens

/api/v8/oauth2/clients/{id}/tokens/{id}

This REST URI path provides actions and information related to OAuth2 client tokens

DELETE /api/v8/oauth2/clients/{id}/tokens/{id}

Description
Deletes the current token
Arguments
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/oauth2/clients/{id}/tokens/{id}

Description
Returns information about the current token
Arguments
Return Value
This API returns a TokenInfo hash with the following keys (information about the current token):
  • kind (string): the token provider
  • user (string): the username for the token
  • token (string): the token value itself
  • ttl (int): the epoch seconds until the token expires
  • expire_seconds (int): the refresh period for how long the token's lifetime is extended when the token is used
  • creation_timestamp (date): the date and time when the token was created
  • info (UndefinedHash): additional information about the token
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/oauth2/clients/{id}/tokens/{id}

Description
Updates attributes of a client token
Arguments
This API takes the following hash argument:
  • refresh_seconds (int): the new refresh seconds value for the token, negative numbers mean that the token never expires
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/oauth2/code

This REST URI path provides OAuth2 authorization code

GET /api/v8/oauth2/code

Description
Returns the OAuth2 authorization code for the Authorization Code Grant Flow
Arguments
This API takes the following hash arguments:
  • type (string): either token (access token) or code (authorization code) giving the type of response
  • client_id (string): identification of client for which the token/code is generated
  • redirect_uri (*string): if the client sent a redirect_uri with the authorization code request, it must
Return Value
This API returns an OAuth2CodeResponse hash with the following keys (OAuth2 code info):
  • code (string): access token or authorization code value
  • type (string): type of code (either "authorization code" or "access token")
Errors
  • 404 Not Found: invalid arguments to API

/api/v8/options

This REST URI path provides actions and information about supported options for various Qorus objects

GET /api/v8/options

Description
Returns a hash of option information for the following objects:
  • block: a hash of supported finite state machine block types, each block type key is then assigned to a hash of options.
  • mapper: a hash of supported mapper options
  • pipeline: a hash of supported pipeline options
  • remote: a hash of supported remote connection schemes and supported options per scheme
  • system: a hash of supported system options that can be overridden in all interfaces

/api/v8/options/file-locations

This REST URI path provides actions and information about supported file location schemes in Qorus

GET /api/v8/options/file-locations

Description
Returns a hash of option information for all supported file location handlers
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):

/api/v8/options/remote

This REST URI path provides actions and information about supported options for Qorus connection objects

GET /api/v8/options/remote

Description
Returns a hash of option information for all supported user connection schemes
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):

/api/v8/orders

This URI path provides information and actions related to workflow order data.

GET /api/v8/orders

Description
Returns a list of hashes for orders for the current workflow matching the search criteria
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: an alternate key for modified
  • desc: return in descending order
  • ids: an alternate key for workflow_instanceid
  • key: an alternate key for keyname
  • keyname: the name of a search key to be used with the keyvalue value(s)
  • keyvalue: the value(s) of workflow order search key(s) to use (optionally used in conjunction with keyname)
  • limit: max number of rows to return, if not given, then the value of the "row-limit" option is used (default: 100)
  • maxmodified: maximum modified date
  • maxstarted: maximum start date
  • minstarted: minimum start date
  • modified: minimum modified date; if this key is not sent with the request, and no keyvaue, keyname or workflow_instanceid keys are sent, then a value one week before the time of the request is assumed
  • offset: row offset
  • sort: columns for sorting the results
  • status: status value(s) (see Workflow, Segment, and Step Status Descriptions for possible values)
  • statuses: an alternate key for status
  • wfid: an alternate key for workflowid
  • workflowid: one or more workflow IDs
  • workflow_instanceid: workflow_instanceid values(s)
Return Value
This API returns NOTHING if no orders match or a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow order instance ID
  • workflowid: the workflow ID
  • workflowstatus: the status of the workflow order instance (see Workflow, Segment, and Step Status Descriptions for possible values)
  • status_sessionid: the application session ID that owns the workflow order instance data or 0 if the data is now owned by any application session
  • started: the start date/time of the workflow order instance
  • completed: the completed date/time for the workflow order instance
  • modified: the last modified date/time of the workflow order instance
  • parent_workflow_instanceid: the parent workflow order ID if present
  • synchronous: if 1, indicates that the order is being executed synchronously
  • business_error: a boolean flag indicating if the workflow order has an error status due to a business error
  • operator_lock: a string giving the username of the user with an operator lock on the order
  • note_count: the number of notes stored against the order
  • warning_count: the number of warnings raised against the order
  • error_count: the number of errors raised against the order
  • custom_status: a custom status for the order
  • priority: the priority of the workflow order
  • scheduled: the future scheduled date for the workflow order (if any)
  • custom_status_desc: a description for the custom status (if any)
  • actions: a list of possible actions on the workflow

PUT /api/v8/orders?action=block

Description
Blocks a list of workflow order data instances. The operation will fail on workflow orders with status OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatBlocked status (unless the workflow instance is recovered back from OMQ::StatBlocked or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow instance IDs to block; a comma-separated string will be split into a list
Return Value
This API returns a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or a hash with the following key:
  • workflow_status: the status of the workflow order
Failure reasons include:
  • "BLOCK-WORKFLOW-ERROR": invalid status, foreign session id, missing original status, unblock operation already in progress
  • "WORKFLOW-ACCESS-ERROR": the user does not have the right to access the given workflow (for more information, see Interface Groups)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_BLOCK_WORKFLOW_ORDER
See also

PUT /api/v8/orders?action=cancel

Description
Cancels one or more workflow order data instances by changing the status for the workflow order data instances to OMQ::StatCanceled. The operation will fail if the workflow order status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatCanceled status (unless the workflow instance is recovered back from OMQ::StatCanceled or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Return Value
This API returns a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or a hash with the following key:
  • workflow_status: the status of the workflow order
Errors
  • 409 Conflict: CANCEL-WORKFLOW-ERROR: invalid status, foreign session id, missing original status, uncancel operation already in progress
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_CANCEL_WORKFLOW_ORDER
See also

GET /api/v8/orders?action=listErrors

Description
Returns information about workflow order errors corresponding to the search arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • workflow_instanceid: limit the search to one or more workflow_instanceids
  • error_instanceid: limit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • workflowid: limit the search to one or more workflowids
  • workflowstatus: limit the search to workflow instances with the given status value(s)
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

GET /api/v8/orders?action=processingSummary

Description
Returns information about workflow processing.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • mindate: (required) minimum date
  • maxdate: maximum date
  • wfids: optional workflow IDs
  • seconds: if True then the performance values will be returned as arbitrary-precision numeric values representing seconds, otherwise they will be returned as relative date/time values
  • global: if True then all workflows will be combined into an overall processing report, if False then each workflow gets a separate line in the output
  • grouping: (optional) possible values for reporting performance statistics:
    • "hourly": hourly grouping
    • "daily": daily grouping
    • "monthly": monthly grouping
    • "yearly": yearly grouping
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • workflowid: the workflow ID
  • name: the workflow name
  • version: the workflow version
  • count: the number of workflow orders in the period
  • minstarted: the minimum workflow order start date
  • maxcompleted: the maximum workflow order completion date (if any)
  • minduration: the minimum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • avgduration: the average total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • maxduration: the maximum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • minprocessing: the minimum order processing time for workflow orders in the period (starting from when then order was first processed)
  • avgprocessing: the average order processing time for workflow orders in the period (starting from when then order was first processed)
  • maxprocessing: the maximum order processing time for workflow orders in the period (starting from when then order was first processed)
Errors
  • 409 Conflict: ARGUMENT-ERROR: missing mindate

DELETE /api/v8/orders?action=purgeSensitiveData

Description
Deletes sensitive data according to the arguments given
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • skey: (optional) the sensitive data key type; if passed, then svalue must be included
  • svalue: (optional) the sensitive data key value; if passed then skey must be included
  • force: (optional) allows sensitive data to be deleted for workflow orders with statuses other than OMQ::StatComplete or OMQ::StatCanceled
  • maxmodified: (optional) maximum modified date of the workflow order
  • maxstarted: (optional) maximum start date of the workflow order
  • minstarted: (optional) minimum start date of the workflow order
  • modified: (optional) minimum modified date of the workflow order
  • status: (optional) workflow order status value(s)
  • workflow_instanceid: (optional) workflow_instanceid values(s)
  • workflowid: (optional) workflowid values(s)
  • workflowname: (optional) all accessible versions of the given workflow name
Return Value
A list of hashes for matched workflow orders that correspond to the arguments; each hash element has keys as follows:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow order instance ID
  • workflowid: the workflow ID
  • workflowstatus: the status of the workflow order instance
  • status_sessionid: the application session ID that owns the workflow order instance data or 0 if the data is now owned by any application session
  • started: the start date/time of the workflow order instance
  • completed: the completed date/time for the workflow order instance
  • modified: the last modified date/time of the workflow order instance
  • parent_workflow_instanceid: the parent workflow_instanceid if the workflow is a child workflow order
  • synchronous: the synchronous flag for the workflow order instance
  • business_error: the business error flag for the workflow order instance
  • archive: the archive flag for the workflow order instance (presented only if it goes from archive datasource)
  • operator_lock: the username of the user owning the lock on the workflow order instance data
  • note_count: the number of notes attached to the workflow order instance
  • warning_count: the warning count of the workflow order instance
  • error_count: the error count of the workflow order instance
  • custom_status: any custom status for the workflow order instance
  • priority: the priority of the workflow order instance
  • scheduled: the scheduled date for the workflow order instance
  • archive: if retrieved from the archive datasource
  • skey: the sensitive data key type
  • svalue: the sensitive data value; if the svalue key is given in the request, then it's returned decoded, otherwise the encoded version is returned'
  • sensitive_data: the sensitive data hash for the given key and value
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SENSITIVE-DATA-ERROR: the request to search for sensitive data arrived over a non-encrypted network connection or skey included without svalue or svalue included without skey
  • 409 Conflict: INVALID-WORKFLOW: the name given in the workflowname parameter does not correspond to a known workflow
  • 409 Conflict: ORDER-STATUS-ERROR: a status other than OMQ::StatComplete or OMQ::StatCanceled was passed and the force option was not given and the workflow_instanceid option was used
Note
  • requires permission OMQ::QR_DELETE_SENSITIVE_DATA or OMQ::QR_SENSITIVE_DATA_CONTROL
  • sensitive data can only be queried over a secure connection
  • the ORDER-STATUS-ERROR is only thrown if the force option is not True and the workflow_instanceid option is used, otherwise ineligible orders are ignored
  • this method operates on the system schema and any archiving schema, treating both as a single unified schema transparently
  • this method is not implemented in the system.info service to avoid inadvertent logging of sensitive data
See also

PUT /api/v8/orders?action=retry

Description
Retries the given workflow order instances. In order to make a retry; the workflow order status for each order must be OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow instance IDs to retry; a comma-separated string will be split into a list
Return Value
This API returns a hash where the top level key is the workflow_instanceid, and the value is either an exception string (indicating that the operation failed) or a hash with the following keys:
  • steps_updated: (deprecated) always 0 in this version of Qorus
  • segments_updated: the number of segments updated
  • workflow_updated: always True in this version of Qorus
  • workflow_status: always OMQ::StatRetry in this version of Qorus
  • cached: True if the workflow data is currently cached
Failure reasons include:
  • "STATUS-ERROR": workflow data does not have OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry status
  • "SESSION-ERROR": cannot change status for workflow data managed by another Qorus instance (foreign session ID)
  • "RETRY-ERROR": invalid workflow instance ID
  • "WORKFLOW-ACCESS-ERROR": the user does not have the right to access the given workflow (for more information, see Interface Groups)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RETRY_WORKFLOW_ORDER

GET /api/v8/orders?action=searchSensitiveData

Description
Searches for sensitive data according to the arguments given
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • skey: (required) the sensitive data key type
  • svalue: (required) the sensitive data key value
  • desc: (optional) return in descending order
  • maxmodified: (optional) maximum modified date of the workflow order
  • maxstarted: (optional) maximum start date of the workflow order
  • minstarted: (optional) minimum start date of the workflow order
  • modified: (optional) minimum modified date of the workflow order
  • limit: (optional) max number of rows to return, if not given, then the value of the "row-limit" option is used (default: 100)
  • offset: (optional) row offset
  • sort: (optional) columns for sorting the results
  • status: (optional) workflow order status value(s)
  • workflow_instanceid: (optional) workflow_instanceid values(s)
  • workflowid: (optional) workflowid values(s)
  • workflowname: (optional) all accessible versions of the given workflow name
Return Value
A list of hashes for matched workflow orders that correspond to the arguments; each hash element has keys as follows:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow order instance ID
  • workflowid: the workflow ID
  • workflowstatus: the status of the workflow order instance
  • status_sessionid: the application session ID that owns the workflow order instance data or 0 if the data is now owned by any application session
  • started: the start date/time of the workflow order instance
  • completed: the completed date/time for the workflow order instance
  • modified: the last modified date/time of the workflow order instance
  • parent_workflow_instanceid: the parent workflow_instanceid if the workflow is a child workflow order
  • synchronous: the synchronous flag for the workflow order instance
  • business_error: the business error flag for the workflow order instance
  • archive: the archive flag for the workflow order instance (presented only if it goes from archive datasource)
  • operator_lock: the username of the user owning the lock on the workflow order instance data
  • note_count: the number of notes attached to the workflow order instance
  • warning_count: the warning count of the workflow order instance
  • error_count: the error count of the workflow order instance
  • custom_status: any custom status for the workflow order instance
  • priority: the priority of the workflow order instance
  • scheduled: the scheduled date for the workflow order instance
  • archive: if retrieved from the archive datasource
  • skey: the sensitive data key type
  • svalue: the sensitive data value
  • sensitive_data: the sensitive data hash for the given key and value
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SENSITIVE-DATA-ERROR: the request to search for sensitive data arrived over a non-encrypted network connection
  • 409 Conflict: INVALID-WORKFLOW: the name given in the workflowname parameter does not correspond to a known workflow
Note
See also

PUT /api/v8/orders?action=unblock

Description
Resets the statuses of one or more blocked workflow order data instances to their original statuses before blocking.
Return Value
This API returns a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or a hash with the following key:
  • workflow_status: the status of the workflow order
Failure reasons include:
  • "BLOCK-WORKFLOW-ERROR": invalid status, foreign session id, missing original status, block operation already in progress
  • "WORKFLOW-ACCESS-ERROR": Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_BLOCK_WORKFLOW_ORDER
See also

PUT /api/v8/orders?action=uncancel

Description
Resets one or more canceled workflow order data instance statuses to their original statuses before canceling.
Return Value
This API returns a hash where the top-level key is the workflow_instanceid, and each value is either an exception string (indicating that the operation for that workflow_instanceid failed) or a hash with the following key:
  • workflow_status: the status of the workflow order
Failure reasons include:
  • "CANCEL-WORKFLOW-ERROR": invalid status, foreign session id, missing original status, cancel operation already in progress
  • "WORKFLOW-ACCESS-ERROR": Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Errors
  • 400 Bad Request: all uncancel operations failed
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
See also

/api/v8/orders/{id}

This REST URI path provides actions and information about specific workflow orders.

GET /api/v8/orders/{id}

Description
Returns information about the current workflow order data instance
Arguments
Return Value
This API returns a WorkflowOrderInfo hash with the following keys (detailed information about the workflow order):
  • name (string): the name of the workflow
  • version (string): the version of the workflow
  • author (*string): the author of the workflow
  • patch (*string): the workflow patch string (if any)
  • workflow_instanceid (int): the workflow order instance ID
  • workflowid (int): the ID of the workflow
  • workflowstatus (string): the status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
  • status_sessionid (int): the ID of the Qorus application session managing the workflow order data or 0 if none
  • parent_workflow_instanceid (*int): the workflow order instance ID of the parent order for this workflow if any
  • subworkflow (*bool): indicates if the parent_workflow_instanceid is the parent workflow order in a subworkflow relationship
  • synchronous (bool): indicates if the order is being executed synchronously
  • archive (*bool): indicates if the order has been archived
  • business_error (bool): indicates if the workflow order has an error status due to a business error
  • workflowstatus_orig (*string): if the order status is OMQ::StatBlocked or OMQ::StatCanceled, this value will reflect the original status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
  • custom_status (*string): a custom status for the order
  • scheduled (*date): the scheduled date
  • priority (int): the priority of the workflow order
  • started (date): the date/time the order was created
  • completed (*date): the date/time order processing completed
  • modified (date): the last modified date/time for the order
  • operator_lock (*string): a string giving the username of the user with an operator lock on the order
  • note_count (int): the number of notes stored against the order
  • deprecated (bool): a boolean value indicating if the workflow is deprecated or not; deprecated workflows are hidden by default in the UI
  • autostart (int): the integer autostart value for the workflow
  • manual_autostart (bool): a boolean flag set if the autostart value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • max_instances (*int): a value limiting the maximum number of execution instances that can run at once
  • external_order_instanceid (*string): a unique external key for the order
  • staticdata (*UndefinedHash): a hash of workflow order static data
  • dynamicdata (*UndefinedHash): a hash of workflow order dynamic data (if any)
  • sensitive_data (*SensitiveDataSetInfo): any sensitive data information for the workflow; this information is only present when retrieving the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values
    • key (SensitiveDataKeyInfo): SensitiveDataKeyInfo value
  • has_sensitive_data (bool): indicates if the order has sensitive data
  • stepdata (*list<StepDataInfo>): a list of step data information
  • keys (*OrderKeySet): a hash of workflow order keys and values
    • key (*list<string>): *list<string> value
  • warning_count (int): the number of warnings raised against the order
  • error_count (int): the number of errors raised against the order
  • retry_count (int): the number of times the order was subject to a RETRY status due to a technical error
  • StepInstances (list<StepInstanceInfo>): a list of step hashes giving information about the execution status of workflow steps
  • ErrorInstances (*list<ErrorInstanceInfo>): a list of hashes giving information about errors and warnings raised against the order
  • HierarchyInfo (OrderHierarchySetInfo): a hash of workflow order information; the keys are workflow order instance IDs for all workflow orders linked to each other through parent-child relationships in the hierarchy of the current workflow order
    • name (string): the name of the workflow
    • version (string): the version of the workflow
    • workflow_instanceid (int): the workflow order instance ID
    • workflowid (int): the ID of the workflow
    • workflowstatus (string): the status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
    • status_sessionid (int): the ID of the Qorus application session managing the workflow order data or 0 if none
    • parent_workflow_instanceid (*int): the workflow order instance ID of the parent order for this workflow if any
    • subworkflow (*bool): indicates that the parent_workflow_instanceid is the parent workflow order in a subworkflow relationship
    • synchronous (bool): indicates that the order is being executed synchronously
    • retries (*int): the number of retries executed on the order
    • note_count (int): the number of notes stored against the order
    • business_error (bool): indicates if the workflow order has an error status due to a business error
    • workflowstatus_orig (*string): if the order status is OMQ::StatBlocked or OMQ::StatCanceled, this value will reflect the original status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
    • custom_status (*string): a custom status for the order
    • scheduled (*date): the scheduled date
    • priority (int): the priority of the workflow order
    • started (date): the date/time the order was created
    • completed (*date): the date/time order processing completed
    • modified (date): the last modified date/time for the order
    • operator_lock (*string): a string giving the username of the user with an operator lock on the order
    • patch (*string): the workflow patch string (if any)
    • author (*string): the author of the workflow
    • description (*string): an optional description of the workflow
    • remote (bool): the remote status of the workflow
    • open (bool): if the current workflow is open for processing now
    • autostart (int): the autostart value
    • enabled (bool): if the worklfow is currently enabled for execution
    • sla_threshold (int): the number of seconds in which workflow orders should receive a final status
    • deprecated (bool): the deprecated flag
    • created (date): the creation date
    • custom_status_desc (*string): the custom status description, if any
    • workflow_modules (*list<string>): any modules associated with the workflow
    • hierarchy_level (int): the level in the workflow order hierarchy
    • error_count (int): number of errors
    • warning_count (int): number of warnings
  • AuditEvents (*list<UndefinedHash>): a list of audit information hashes
  • LastModified (date): the last modified date/time of the workflow order
  • staticdata_type_path (*UndefinedHash): type info for the workflow's static data, if any
  • actions (*list<string>): a list of possible actions on the workflow
  • notes (*list<NoteInfo>): a list of notes saved against the order

PUT /api/v8/orders/{id}?action=block

Description
Blocks the current workflow order data instance by changing its status to BLOCKED. An exception will be thrown if the status is IN-PROGRESS. No further processing can be done on workflow order data instances with a CANCELED status (unless the workflow order instance is recovered back from CANCELED to its original status or the status is first updated to ERROR and then to RETRY). Note that CANCELED and BLOCKED statuses have the same effect, however CANCELED is meant to be a permanent or final status, while BLOCKED is meant to be temporary.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=breakLock

Description
Breaks the current workflow order lock so that it can be updated by any authorized user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (required) a string note that gives the reason for breaking the operator lock
Return Value
This API returns "OK" upon successful execution
Note
See also

POST /api/v8/orders/{id}?action=breakUserInteractionStepLock

Description
Qorus 4.0.1
Arguments
This API takes the following hash arguments:
  • stepid (int): the step ID of the step
  • ind (int): the step instance index value; use 0 for non-array steps
  • note (string): a note to be added to the order on why the lock was broken
Return Value
This API returns a value of type string: "OK"
Errors
  • 400 Bad Request: invalid arguments
  • 403 Forbidden: access or authorization error
  • 404 Not Found: the given stepid and ind values do not exist in the workflow order or the step is not an asynchronous step with the user-interaction API enabled
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=cancel

Description
Blocks the current workflow order data instance by changing its status to CANCELED. An exception will be thrown if the status is IN-PROGRESS. No further processing can be done on workflow order data instances with a CANCELED status (unless the workflow order instance is recovered back from CANCELED to its original status or the status is first updated to ERROR and then to RETRY). Note that CANCELED and BLOCKED statuses have the same effect, however CANCELED is meant to be a permanent or final status, while BLOCKED is meant to be temporary.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=dynamicData

Description
Replaces the dynamic data for the current order
Arguments
This API takes the following hash argument:
  • newdata (*hash<auto>): the new dynamic data for the current workflow order
Return Value
This API returns a value of type string: OK
Errors
  • 400 Bad Request: invalid or missing argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/orders/{id}?action=execSynchronous

Description
Executes a workflow in synchronous mode against the current order, which must have status OMQ::StatReady or OMQ::StatScheduled; it is not possible to process workflow data with other statuses synchronously.
The call will normally return only after the workflow reaches a OMQ::StatComplete or OMQ::StatError state, unless the system or the workflow order data instance are manually stopped while the workflow order data instance is being processed, in which case other statuses can be returned.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: (hash) an optional hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the synchronous workflow execution instance is not started
Return Value
This API returns a hash with the following keys:
  • workflow_instanceid: the workflow instance ID of the order
  • status: the status of the workflow
  • dynamicdata: the dynamic data of the workflow order instance
Errors
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: cannot start new workflows because the system is shutting down
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires at least one of the following permissions: OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_EXEC_SYNC_WORKFLOW
See also

GET /api/v8/orders/{id}?action=listErrors

Description
Returns information about workflow order errors for the given workflow order instance
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • error_instanceid: mit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

PUT /api/v8/orders/{id}?action=lock

Description
Locks the current workflow order so that it can only be updated by the current user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (required) a string note that gives the reason for setting the operator lock
Return Value
This API returns "OK" upon successful execution
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_LOCK_WORKFLOW_ORDER
See also

POST /api/v8/orders/{id}?action=lockUserInteractionStep

Description
Qorus 4.0.1
Arguments
This API takes the following hash arguments:
  • stepid (*int): the ID of the step to acquire user interaction data from; either this or stepname is required
  • stepname (*string): the name of the step to acquire user interaction data from; either this or stepid is required
Return Value
This API returns a WorkflowLockUseInteractionStepResultInfo hash with the following keys (information about the result of the operation):
  • workflow_instanceid (int): the workflow order instance ID
  • stepid (int): the step ID of the step
  • ind (int): the step instance index number
  • queuekey (string): the queue key ID
  • queueid (int): the ID of the async queue
  • queuename (string): the name of the async queue
  • data (*UndefinedHash): any step data already present
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no data available on the queue to lock
Note
Requires one of the following permissions:

GET /api/v8/orders/{id}?action=notes

Description
Returns a list of notes saved against the order; each element is a REST Order Note Hash.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • limit: the maximum number of notes to return; if omitted then all notes are returned
Return Value
This API returns a list of hashes of notes saved against the order; each element is a REST Order Note Hash.
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

POST /api/v8/orders/{id}?action=notes

Description
Creates an order note on the current workflow order
Arguments
This API takes the following hash argument:
  • note (string): the note to create on the order
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/orders/{id}?action=releaseUserInteractionStepLock

Description
Qorus 4.0.1
Arguments
This API takes the following hash arguments:
  • stepid (int): the step ID of the step
  • ind (int): the step instance index value; use 0 for non-array steps
Return Value
This API returns a value of type string: "OK"
Errors
  • 400 Bad Request: invalid arguments
  • 403 Forbidden: access or authorization error, lock held by another user
  • 404 Not Found: the given stepid and ind values do not exist in the workflow order or the step is not an asynchronous step with the user-interaction API enabled
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=reschedule

Description
Sets or removes the scheduled date for the current workflow order data instance. Setting the scheduled date for a workflow order means that the workflow order data will not be processed before the scheduled date and time. The workflow order data must normally have status OMQ::StatReady or OMQ::StatScheduled to be rescheduled, however also workflows with OMQ::StatCanceled and OMQ::StatBlocked statuses can be rescheduled if their original status is OMQ::StatReady or OMQ::StatScheduled.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: (optional) parsed as a date; this is the new scheduled date to set; if not present, then any scheduled date will be removed
Return Value
This API returns "OK" upon successful execution
Errors
  • 409 Conflict: SESSION-ERROR: cannot reschedule workflow data owned by a foreign session
  • 409 Conflict: WORKFLOW-STATUS-ERROR: only workflows with status OMQ::StatReady or OMQ::StatScheduled or blocked or canceled workflows with original status OMQ::StatReady or OMQ::StatScheduled can be rescheduled
  • 409 Conflict: RESCHEDULE-ERROR: reschedule failed because workflow order data started processing while the request was being processed
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RESCHEDULE_WORKFLOW_ORDER
See also

PUT /api/v8/orders/{id}?action=retry

Description
Retries the current workflow order instance; in order to make a retry; the workflow order status must be OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry.
Return Value
This API returns a hash with the following keys:
  • steps_updated: (deprecated) always 0 in this version of Qorus
  • segments_updated: the number of segments updated
  • workflow_updated: always True in this version of Qorus
  • workflow_status: always OMQ::StatRetry in this version of Qorus
  • cached: True if the workflow data is currently cached
Errors
  • 409 Conflict: STATUS-ERROR: workflow data does not have either OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry status
  • 409 Conflict: SESSION-ERROR: cannot change status for workflow data managed by another Qorus instance (foreign session ID)
  • 409 Conflict: RETRY-ERROR: invalid workflow instance ID
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RETRY_WORKFLOW_ORDER
See also
omq.system.retry-workflow-instances()

PUT /api/v8/orders/{id}?action=sensitiveData

Description
Replaces the sensitive data for the current order given the sensitive data key and
Arguments
This API takes the following hash arguments:
  • skey (string): the sensitive data key type
  • svalue (string): the sensitive data key value
  • aliases (*list<string>): zero or more string aliases for the sensitive data
  • data (*UndefinedHash): the sensitive data hash itself; if omitted then sensitive data is removed for the given skey and svalue values
  • meta (*SensitiveMetaInfo): a hash of metadata for the sensitive data
    • PURPOSE (auto): free-form information about the purpose of the sensitive data
    • CATEGORIES (auto): free-form information about the categories of sensitive data
    • RECIPIENTS (auto): free-form information about the recipients or recipient catories of sensitive data
    • STORAGE (auto): free-form information about the storage time or rules for sensitive data
Return Value
This API returns a value of type string: "OK"
Errors
  • 400 Bad Request: invalid arguments or request made over a non-encrypted connection
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=setError

Description
Changes the status of a workflow order data instance to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting. If the status is any other status, an exception will be thrown.

To set a workflow order data instance with a OMQ::StatWaiting status to OMQ::StatError, set the child workflows to OMQ::StatError first and the status of the parent workflow order will be updated automatically.

When setting a workflow order from OMQ::StatCanceled to OMQ::StatError, outstanding events will be queued and the associated queued event keys will be present in the return value.
Return Value
This API returns a hash with the following keys:
  • steps_updated: number of steps updated
  • segments_updated: number of segments updated
  • workflow_status: always OMQ::StatError
  • old_status: the old workflow data status
  • queued_detached_segments: number of detached segment events queued
  • queued_subworkflows: number of subworkflow events queued
  • queued_async_messages: number of async events queued
  • queued_sync_events: number of workflow synchronization events queued
  • queued_async_retries: number of async events queued
  • queued_retries: number of retry events queued
  • queued_fixed_retries: number of retry events with a fixed retry time queued
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_WORKFLOW_ORDER_ERROR
See also

PUT /api/v8/orders/{id}?action=setPriority

Description
Changes the priority for an existing workflow order data instance. The workflow order data must not have status OMQ::StatComplete.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • priority: the new order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
Return Value
This API returns "OK" upon successful execution
Errors
  • 409 Conflict: SESSION-ERROR: cannot reschedule workflow data owned by a foreign session
  • 409 Conflict: WORKFLOW-STATUS-ERROR workflows with status OMQ::StatComplete cannot have their priority changed
  • 403 Forbidden: AUTHORIZATION-ERROR this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_REPRIORITIZE_WORKFLOW_ORDER
See also

PUT /api/v8/orders/{id}?action=skipStep

Description
Skips execution of a step in the current workflow order. Sometimes execution for a given step must be skipped, but the rest of the workflow logic should be executed. This API call allows Qorus to continue executing a workflow order data instance after skipping the given step. Only steps with OMQ::StatError, OMQ::StatRetry, OMQ::StatEventWaiting, or OMQ::StatAsyncWaiting can be skipped. Subworkflow steps with any status cannot be skipped; the child workflow must be corrected instead.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stepid: (required) the step ID to skip
  • ind: (optional) one or more step array index values to skip (ranges accepted; ex: "1,3,5-7"); if not present defaults to 0
  • noretry: (optional) parsed with Qore::parse_boolean(); if True then no retry will be executed
Errors
  • 409 Conflict: SKIP-STEP-ERROR: step is a subworkflow step; step has not been executed in the given workflow order instance; the given workflow instance ID does not exist
  • 409 Conflict: STEP-STATUS-ERROR: step status does not allow it to be skipped (ex: IN-PROGRESS, COMPLETE)
  • 409 Conflict: SESSION-ERROR: workflow order instance belongs to another Qorus session
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

PUT /api/v8/orders/{id}?action=staticData

Description
Replaces the static data for the current order
Arguments
This API takes the following hash argument:
  • newdata (hash<auto>): the new static data for the current workflow order; must be a non-empty
Return Value
This API returns a value of type string: OK
Errors
  • 400 Bad Request: invalid or missing argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=stepData

Description
Qorus 4.0.1
Arguments
This API takes the following hash arguments:
  • stepid (int): required: the step ID of the step
  • ind (int): required: the step instance index value; use 0 for non-array steps
  • newdata (*UndefinedHash): required: the new dynamic step data for the current workflow order and step; can also be NOTHING which will remove all step data from the current step
Return Value
This API returns a value of type string: "OK"
Errors
  • 400 Bad Request: invalid arguments
  • 403 Forbidden: access or authorization error
  • 409 Conflict: cannot lock order for updating, order has COMPLETE status
Note
Requires one of the following permissions:

GET /api/v8/orders/{id}?action=stepData

Description
Qorus 4.0.1
Arguments
Return Value
This API returns a *UndefinedHash hash; keys have the following format:
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: the given stepid and ind values do not exist in the workflow order

PUT /api/v8/orders/{id}?action=unblock

Description
Resets the status of a blocked workflow order data instance to its original status before blocking.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=uncancel

Description
Resets the status of a canceled workflow order data instance to its original status before canceling.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/orders/{id}?action=unlock

Description
Unlocks the current workflow order so that it can be updated by any authorized user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (optional) a string note that gives the reason for removing the operator lock; if not passed, a default note will be added
Return Value
This API returns "OK" upon successful execution
Note
See also

PUT /api/v8/orders/{id}?action=updateDynamicData

Description
Updates the dynamic data for an existing order by merging the data passed in the newdata argument to the existing dynamic data hash in an atomic operation
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (hash) data to be merged with the existing dynamic data for the current workflow order
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 5.1.10

PUT /api/v8/orders/{id}?action=updateDynamicDataPath

Description
Updates the dynamic data for an existing order by setting the value provided by the path argument with the value provided by the value argument in the existing dynamic data hash in an atomic operation
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • path: (string) the path to the data to be updated
  • value: (auto) any value to be updated at the location provided by path
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 5.1.10

PUT /api/v8/orders/{id}?action=updateKeys

Description
Replace all order keys for the current workflow order
Arguments
This API takes the following hash arguments:
  • orderkeys (OrderKeySet): the order keys to replace for the current workflow order
    • key (list<string>): list<string> value
  • truncate (*bool): truncate any key values automatically to the length of the column (4000 characters)
Return Value
This API returns an OrderKeySet hash; keys have the following format:
  • any (list<string>): all order keys for the order after updating
Errors
  • 400 Bad Request: invalid orderkeys argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/orders/{id}?action=yamlDynamicData

Description
Returns dynamic data for the order as a serialized YAML string for potential editing
Return Value
This API returns a YAML-serialized string of workflow order dynamic data; if no dynamic data is in place; then YAML-serialized string will be deserialized to a hash or to no value (i.e. in Qore NOTHING) if there is no dynamic data for the workflow order
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • this method operates on the system schema and any archiving schema transparently
Since
Qorus 3.1.1.p1

PUT /api/v8/orders/{id}?action=yamlDynamicData

Description
Replaces the dynamic data for an existing order using a YAML-serialized string for the new dynamic data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (YAML-serialized string) the new dynamic data for the current workflow order as a YAML-serialized string; can also be deserialized to NOTHING which will remove all dynamic data from the order
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: DYNAMIC-DATA-ERROR: this error is returned if the newdata argument is not a string
  • 409 Conflict: YAML-PARSER-ERROR: this error is returned if the YAML string cannot be deserialized
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 3.1.1.p1

PUT /api/v8/orders/{id}?action=yamlSensitiveData

Description
Replaces the sensitive data for an existing order given the sensitive data key and value; the actual sensitive data must be given as a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • skey: (string) the sensitive data key type
  • svalue: (string) the sensitive data key value
  • data: (YAML-serialized string) the new sensitive data for the current workflow order; can also be NOTHING which will remove all sensitive data from the order for the given sensitive data key and value
  • aliases: (string or list of strings; optional) zero or more aliases for the sensitive data corresponding to the given sensitive data key and value
  • meta: (hash; optional) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
    • [PURPOSE]: free-form information about the purpose of the sensitive data
    • [CATEGORIES]: free-form information about the categories of sensitive data
    • [RECIPIENTS]: free-form information about the recipients or recipient catories of sensitive data
    • [STORAGE]: free-form information about the storage time or rules for sensitive data
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SENSITIVE-DATA-ERROR: invalid arguments; cannot update sensitive data over a non-encrypted network connection
  • 409 Conflict: YAML-PARSER-ERROR: this error is returned if the YAML string cannot be deserialized
Note
Since
Qorus 3.1.1.p1

GET /api/v8/orders/{id}?action=yamlSensitiveData

Description
Returns the sensitive data for an existing order given the sensitive data key and value; the sensitive data itself is returned as a YAML-serialized string
Arguments
This API takes the following required hash arguments (either as URI arguments or in the message body):
  • skey: (string) the sensitive data key type
  • svalue: (string) the sensitive data key value
Return Value
This API returns either NOTHING (if the order doesn't have the request sensitive data key and value) or a hash with the following keys:
  • [aliases]: (list of strings) zero or more string aliases for the sensitive data
  • data: (YAML-serialized string) the sensitive data hash itself serialized as a YAML string for potential editing
  • [meta]: (hash) a hash of metadata for the sensitive data with the following recommended keys (recommended keys are not enforced by the API itself):
    • [PURPOSE]: free-form information about the purpose of the sensitive data
    • [CATEGORIES]: free-form information about the categories of sensitive data
    • [RECIPIENTS]: free-form information about the recipients or recipient catories of sensitive data
    • [STORAGE]: free-form information about the storage time or rules for sensitive data
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SENSITIVE-DATA-ERROR: invalid arguments; cannot retrieve sensitive data over a non-encrypted network connection
Note
Since
Qorus 3.1.1.p1

PUT /api/v8/orders/{id}?action=yamlStaticData

Description
Replaces the static data for an existing order using a YAML-serialized string for the new static data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (YAML-serialized string) the new static data for the current workflow order as a YAML-serialized string; must be deserialized to a non-empty hash
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: STATIC-DATA-ERROR: this error is returned if the newdata argument is not a string
  • 409 Conflict: YAML-PARSER-ERROR: this error is returned if the YAML string cannot be deserialized
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 3.1.1.p1

GET /api/v8/orders/{id}?action=yamlStaticData

Description
Returns static data for the order as a serialized YAML string for potential editing
Return Value
This API returns a YAML-serialized string of workflow order static data; if no static data is in place; then YAML-serialized string will be deserialized to a hash or to no value (i.e. in Qore NOTHING) if there is no static data for the workflow order
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
  • this method operates on the system schema and any archiving schema transparently
Since
Qorus 3.1.1.p1

PUT /api/v8/orders/{id}?action=yamlStepData

Description
Replaces the dynamic step data for an existing order using a YAML-serialized string for the new dynamic step data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stepid: (int) required: the step ID of the step
  • ind: (int) required: the step instance index value; use 0 for non-array steps
  • newdata: (YAML-serialized string) required: the new dynamic step data for the current workflow order and step; can also be deserialized to NOTHING which will remove all step data from the current step
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 400 Bad Request: returned if the newdata argument is not a string or cannot be parsed as valid YAML
  • 404 Not Found: the given stepid and ind values do not exist in the workflow order
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 4.0.1

GET /api/v8/orders/{id}?action=yamlStepData

Description
Returns dynamic step data for the order as a serialized YAML string for potential editing
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stepid: (int) required: the step ID of the step
  • ind: (int) required: the step instance index value; use 0 for non-array steps
Return Value
This API returns a YAML-serialized string of workflow order dynamic step data; if no dynamic step data is in place; then a YAML-serialized string representing no value (i.e. "null") will be returned.
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown if Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 404 Not Found: the given stepid and ind values do not exist in the workflow order
Since
Qorus 4.0.1

PUT /api/v8/orders/{id}?action=yamlUpdateDynamicData

Description
Updated the dynamic data for an existing order using a YAML-serialized string as a hash value to be merged with the existing dynamic data in an atomic operation
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (YAML-serialized string) the new dynamic data to be added to the dynamic data for the current workflow order as a YAML-serialized string
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 404 Bad Request: DYNAMIC-DATA-ERROR: this error is returned if the newdata argument is not a string or if the string is not valid YAML
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 5.1.10

PUT /api/v8/orders/{id}?action=yamlUpdateDynamicDataPath

Description
Updates the dynamic data for an existing order by setting the value provided by the path argument with the value provided by the value argument as a YAML-serialized string in the existing dynamic data hash in an atomic operation
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • path: (string) the path to the data to be updated
  • value: (string) a YAML-serialized value to be used to update dynamic data at the location provided by path
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 404 Bad Request: DYNAMIC-DATA-ERROR: this error is returned if the value argument is not a string or if the string is not valid YAML
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA
Since
Qorus 5.1.10

/api/v8/orders/{id}/async-queue

This REST URI path provides actions and information about specific workflow orders' Asynchronous Queue Objects

GET /api/v8/orders/{id}/async-queue

Description
Gets queue information for a particular workflow and step
Arguments
  • stepid the stepid to query. Optional, defaults to 0
  • int the array index offset of the step to query (0 for non-array steps). Optional.
Return Value
A list of hashes or an ampty list is returned.

The queue info hash has the following keys:

  • workflow_instanceid: the workflow instance ID of the step and queue entry
  • stepid: the step ID of the step and queue entry
  • ind: the array index of the step and queue entry (0 for non-array steps)
  • queuekey: the queue key string
  • queue_data_status: the status of the queue entry: OMQ::QS_Waiting, OMQ::QS_Received, OMQ::QS_Used (Oracle only), or OMQ::QS_Error (rarely, in case of unparsable queue data)
  • corrected: if 1, then the queue entry has been corrected. meaning that the back-end function will not be executed and the step will automatically get a OMQ::StatComplete status.
  • data: the queue data, if any, set only when the queue data status is OMQ::QS_Received
Exceptions
GET-INFO-ERRORinvalid workflow_instanceid
WORKFLOW-ACCESS-ERRORthis is exeption is thrown when RBAC is enabled, and the call is made externally, and the user does not have the right to access the given workflow

POST /api/v8/orders/{id}/async-queue?action=correct

Description
corrects a queue entry with status OMQ::QS_Waiting, sets the status to OMQ::QS_Received and sets the corrected attribute to True

This will effective cause an asynchronous step to be skipped without the back end function being run at all; the step will be processed to OMQ::StatComplete as soon as the corrected queue entry is delivered to workflow execution instance processing this order. See Asynchronous Queue Objects

Arguments
  • stepid the stepid to update
  • ind the array index offset of the step to update (0 for non-array steps)
Exceptions
QUEUE-CORRECT-DATA-ERRORinvalid workflow_instanceid or stepid
INVALID-WORKFLOW-DATAno queue data for the given step
INVALID-STATUSqueue entry does not have status OMQ::QS_Waiting
ALREADY-CORRECTEDqueue entry has already been corrected
WORKFLOW-ACCESS-ERRORthis is exeption is thrown when RBAC is enabled, and the call is made externally, and the user does not have the right to access the given workflow

/api/v8/orders/{id}/staticdata_type

This REST URI path provides information about workflow static data types

GET /api/v8/orders/{id}/staticdata_type

Description
Returns data type information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/perms

This REST URI path provides actions and information related to RBAC permissions

GET /api/v8/perms

Description
Returns a list of information about permissions
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
Returns a list of REST Permission Hash elements

POST /api/v8/perms

Description
Creates a new user permission
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: (required string) the name of the new user permission
  • desc: (required string) the description for the new user permission
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_PERMISSION

/api/v8/perms/{perm}

This REST URI path provides actions and information related to a specific RBAC permission

DELETE /api/v8/perms/{perm}

Description
Permanently deletes the current permission
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_DELETE_PERMISSION

GET /api/v8/perms/{perm}

Description
Returns information about the current permission
Return Value
Returns a REST Permission Hash for the current permission

PUT /api/v8/perms/{perm}

Description
Updates the current permission
Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • desc: (required string) the new description for the current permission
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_PERMISSION

PUT /api/v8/perms/{perm}?action=update

Description
Updates the current permission
See also
This API is equivalent to PUT /api/perms/{perm}; see that documentation for details.

/api/v8/pipelines

This REST API path provides actions and information related to Qorus Data pipelines.

GET /api/v8/pipelines

Description
Returns a list of hashes describing data pipelines in Qorus
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):

POST /api/v8/pipelines

Description
Creates a new pipeline
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the pipeline
  • display_name (*string): the new display name for the pipeline; generated from name if necessary
  • short_desc (*string): the short plain-text description for the pipeline
  • desc (string): the new description for the pipeline with markdown formatting
  • groups (*list<string>): interface groups that the pipeline belongs to
  • input_provider (*UndefinedHash): the input provider for the pipeline
  • input_provider_options (*UndefinedHash): any options for the input provider
  • children (UndefinedHash): the element and queue definitions for the pipeline
  • options (*UndefinedHash): options for the pipeline
Return Value
This API returns a CreatePipelineInfo hash with the following keys (a description of the new pipeline):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/pipelines?action=create

Description
Creates a new pipeline
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the pipeline
  • display_name (*string): the new display name for the pipeline; generated from name if necessary
  • short_desc (*string): the short plain-text description for the pipeline
  • desc (string): the new description for the pipeline with markdown formatting
  • groups (*list<string>): interface groups that the pipeline belongs to
  • input_provider (*UndefinedHash): the input provider for the pipeline
  • input_provider_options (*UndefinedHash): any options for the input provider
  • children (UndefinedHash): the element and queue definitions for the pipeline
  • options (*UndefinedHash): options for the pipeline
Return Value
This API returns a CreatePipelineInfo hash with the following keys (a description of the new pipeline):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/pipelines/{name}

This REST API path provides actions and information related to a particular Qorus Data pipeline

DELETE /api/v8/pipelines/{name}

Description
Deletes the current data pipeline
Arguments
Return Value
This API returns a PipelineDeletionResult hash with the following keys (data pipeline deletion info):
  • name (string): the name of the mapper deleted
  • pipelineid (string): the ID of the data pipeline deleted
  • mapperid (string): the ID of the mapper deleted
  • version (string): the version of the mapper deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no suchdata pipeline
Note
Requires one of the following permissions:

GET /api/v8/pipelines/{name}

Description
Returns the description of the Data pipeline

PUT /api/v8/pipelines/{name}

Description
Updates the current pipeline
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the pipeline
  • display_name (*string): the new display name for the pipeline; generated from name if necessary
  • short_desc (*string): the short plain-text description for the pipeline
  • desc (*string): the new description for the pipeline with markdown formatting
  • groups (*list<string>): interface groups that the pipeline belongs to
  • input_provider (*UndefinedHash): the input provider for the pipeline
  • input_provider_options (*UndefinedHash): any options for the input provider
  • children (UndefinedHash): the element and queue definitions for the pipeline
  • options (*UndefinedHash): options for the pipeline
Return Value
This API returns an UpdatePipelineInfo hash with the following keys (a description of the new pipeline):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/pipelines/{name}?action=clone

Description
Clones the current pipeline; all parameters are optional and override the cloned pipeline's values. If no name is provided, then a new name is generated for the cloned pipeline
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the pipeline
  • display_name (*string): the new display name for the pipeline; generated from name if necessary
  • short_desc (*string): the short plain-text description for the pipeline
  • desc (*string): the new description for the pipeline with markdown formatting
  • groups (*list<string>): interface groups that the pipeline belongs to
  • input_provider (*UndefinedHash): the input provider for the pipeline
  • input_provider_options (*UndefinedHash): any options for the input provider
  • children (UndefinedHash): the element and queue definitions for the pipeline
  • options (*UndefinedHash): options for the pipeline
Return Value
This API returns a ClonePipelineInfo hash with the following keys (a description of the new pipeline):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/pipelines/{name}?action=file

Description
Returns the pipeline as a file that can be saved

/api/v8/pipelines/{name}/config

This REST URI path provides actions and information related to Qorus Data pipeline configuration items

GET /api/v8/pipelines/{name}/config

Description
Returns a list of Data pipeline configuration items for the Data pipeline
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "pipeline:name1", "pipeline:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

GET /api/v8/pipelines/{name}/config?action=yaml

Description
Returns a list of configuration items for the Data pipeline as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "pipeline:name1", "pipeline:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/pipelines/{name}/config/{name}

This REST URI path provides actions and information related to a particular configuration item for a particular Qorus Data pipeline.

Prefixes can be passed within the config item name or as following: /v5/pipelines/{name}/config/{name}?prefix={prefix}.

DELETE /api/v8/pipelines/{name}/config/{name}

Description
Permanently deletes the current value for the configuration item for the current Data pipeline
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/pipelines/{name}/config/{name}

Description
Returns a hash for the current Data pipeline configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "pipeline:name1", "pipeline:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

PUT /api/v8/pipelines/{name}/config/{name}

Description
Sets the value for the given Data pipeline configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/pipelines/{name}/config/{name}?action=yaml

Description
Sets the value for the given Data pipeline configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/pipelines/{name}/config/{name}?action=yaml

Description
Returns a hash for the current Data pipeline configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "pipeline:name1", "pipeline:name2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

DELETE /api/v8/pipelines/{name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item for this Data pipeline on the local level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/releases

This REST URI path provides actions and information about Qorus releases

GET /api/v8/releases

Description
Returns a list of hashes of information about release that match the search arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • component: the component name to search for (implies with_files = True and with_components = True)
  • component_maxdate: the upper date range for the release search for component (implies with_files = True and with_components = True)
  • component_mindate: the lower date range for the release search for component (implies with_files = True and with_components = True)
  • file_maxdate: give the upper date range for the release search for files (implies with_files = True)
  • file_mindate: give the lower date range for the release search for files (implies with_files = True)
  • file_name: the file name to search for; note that this is used with the SQL like operator (implies with_files = True)
  • limit: the maximum number of releases to return
  • maxdate: give the upper date range for the release search
  • mindate: give the lower date range for the release search
  • offset: the starting release to return (use when paging for example)
  • with_components: if True then file components are in
Return Value
This API returns a list of hashes matching the arguments; each hash element has the following keys:
  • name: the name of the release
  • description: the description of the release
  • created: the date/time the release was created
  • modified: the date/time the release was last modified

/api/v8/releases/{release}

This REST URI path provides actions and information about a specific Qorus release

GET /api/v8/releases/{release}

Description
Returns a hash of information about the current release
Return Value
This API returns a hash with the following keys:
  • name: the name of the release
  • description: the description of the release
  • created: the date/time the release was created
  • modified: the date/time the release was last modified
  • files: a list of file components of the release; each list element is a hash with the following keys:
    • name: the full file path
    • type: the type of file
    • hash_type: the type of cryptographic hash for the file
    • hash: the cryptographic hash value of the file
    • created: the date/time the file entry was created with the release
    • modified: the last modified date/time of the file entry
    • components: a list of object components created from the file; each list element is a hash with the following keys:
      • component: the name of the component
      • version: the version of the component
      • id: the ID of the component (ex: if type = "FUNCTION", then id is a function ID)
      • content_id: the component content ID
      • hash_type: the type of cryptographic hash for the file
      • hash: the cryptographic hash value of the file
      • created: the date/time the file entry was created with the release
      • modified: the last modified date/time of the file entry

/api/v8/remote

This REST URI path provides actions and information about remote Qorus, user and datasource connections

GET /api/v8/remote

Description
Returns a list of child URI path components
Return Value
Returns a list of child URI path components as follows:

GET /api/v8/remote?action=all

Description
Returns a list of all remote connections (remote connections under "qorus", user connections under "user", and datasource connections under "datasources")
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
Returns a list of hashes; the "conntype" value determines the hash format as follows:
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
See also

GET /api/v8/remote?action=list

Description
Returns a list of child URI path components
See also
This API is equivalent to GET /api/remote; see that documentation for details.

/api/v8/remote/datasources

This REST URI path provides actions and information related to Qorus system datasources

GET /api/v8/remote/datasources

Description
Returns a list of hashes providing information for all Qorus system datasources
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of REST Datasource Connection Hash elements
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
the use of the with_passwords argument requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_READ_DATASOURCE
See also

POST /api/v8/remote/datasources

Description
Creates a new datasource connection from the arguments
Arguments
This API takes the following hash arguments:
  • name (*string): the internal name of the connection
  • display_name (*string): the display name of the connection
  • short_desc (*string): the plain-text short description for the new connection
  • desc (*string): the description for the new connection with markdown formatting
  • url (string): the connection string for the new connection; see parse_datasource()
Return Value
This API returns a NewConnectionInfo hash with the following keys (information about the connection created):
  • id (int): the new connection ID
  • name (string): the name of the new connection
  • display_name (string): the display name of the new connection
  • short_desc (string): the connection's description in plain text
  • desc (string): the connection's description with markdown formatting
  • info (string): a string describing the operation performed
  • action (string): the action performed
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/remote/datasources?action=defaultLogger

Description
Set logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/remote/datasources?action=defaultLogger

Description
Create default Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/remote/datasources?action=defaultLogger

Description
Delete logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/remote/datasources?action=defaultLogger

Description
Returns default logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services/qdsp). If set means default logger

PUT /api/v8/remote/datasources?action=defaultLoggerAppenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/remote/datasources?action=defaultLoggerAppenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/remote/datasources?action=defaultLoggerAppenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/remote/datasources?action=defaultLoggerAppenders

Description
Return all logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

PUT /api/v8/remote/datasources?action=flush

Description
removed since Qorus 4.0
Return Value
This API returns a hash with the following key:
  • info: a string indicating that no action was taken; this API no longer has any function
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_FLUSH_DATASOURCE
See also

GET /api/v8/remote/datasources?action=list

Description
Returns a list of hashes providing information for all Qorus system datasources
See also
This API is equivalent to GET /api/remote/datasources; see that documentation for details.

PUT /api/v8/remote/datasources?action=reload

Description
Reloads all datasources from the system database
Return Value
This API returns a hash with the following key:
  • info: a string confirming the reload operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_RELOAD_DATASOURCE

/api/v8/remote/datasources/{name}

This REST URI path provides actions and information related to a specific Qorus system datasource

DELETE /api/v8/remote/datasources/{name}

Description
Deletes the given datasource from the server's internal cache
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: DATASOURCE-ERROR: this exception is thrown if the given datasource does not exist or is a system datasource
Note

GET /api/v8/remote/datasources/{name}

Description
Returns a hash information for the current datasource
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a REST Datasource Connection Hash
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
the use of the with_password argument requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_READ_DATASOURCE

PUT /api/v8/remote/datasources/{name}

Description
Updates the current datasource in the server's internal cache
Arguments
This API takes a hash argument (either as URI arguments or in the message body):
  • desc: (required string) the description for the new connection
  • url: (required string) the connection string for the new connection. See Qore::SQL::parse_datasource()
  • options: (optional hash) a hash of options for the connection; also accepts "opts" as an alias for this option
Return Value
This API returns a hash with the following key:
  • info: a string confirming the update operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: DATASOURCE-ERROR: this exception is thrown if the call tries to modify a locked system datasource or invalid options are passed
Note
See also

POST /api/v8/remote/datasources/{name}?action=clone

Description
Clones the current connection; all parameters are optional and override the cloned connection's values. If no name is provided, then a new name is generated for the cloned connection
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the connection
  • display_name (*string): the new display name for the connection; generated from name if necessary
  • short_desc (*string): the short plain-text description for the connection
  • desc (*string): the new description for the connection with markdown formatting
  • url (*string): the new URL for the connection
  • options (*UndefinedHash): any options for the connection
Return Value
This API returns a CloneConnectionInfo hash with the following keys (a description of the new connection):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/remote/datasources/{name}?action=disable

Description
Disables current datasource
Return Value
This API returns a hash with the following key:
  • info: a string confirming the disable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_MODIFY_DATASOURCE

PUT /api/v8/remote/datasources/{name}?action=enable

Description
Enables current datasource
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_MODIFY_DATASOURCE

GET /api/v8/remote/datasources/{name}?action=file

Description
Returns the connection as a file that can be saved

PUT /api/v8/remote/datasources/{name}?action=ping

Description
Checks connectivity to the current datasource; if the datasource connection was up and is monitored to be down, then any dependent interfaces will be disabled. If the connection was down and is monitored to be up, then any eligible interfaces will be reenabled.
Return Value
This API returns a hash with the following keys:
  • ok: the status of the ping
  • name: the name of the connection
  • desc: the description of the connection
  • url: the URL for the connection
  • opts: a hash of options for the connection (if any)
  • time: the elapsed time for the ping
  • info: "OK" if the ping was successful or an error message if not
  • result: a string representation of the time in seconds (ex: "0.25s")
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_READ_DATASOURCE

PUT /api/v8/remote/datasources/{name}?action=reset

Description
Resets the current datasource; after this call, any new requests for instances of this datasource will result in a new datasource or datasource pool being opened
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
See also
qdsp Datasource Resets
Note
requires permission OMQ::QR_DATASOURCE_CONTROL or OMQ::QR_RESET_DATASOURCE

PUT /api/v8/remote/datasources/{name}?action=update

Description
Temporarily updates the current datasource
See also
This API is equivalent to PUT /api/remote/datasources/{name}; see that documentation for details.

/api/v8/remote/datasources/{name}/provider

This URI path provides access to a data provider created from a datasource

DELETE /api/v8/remote/datasources/{name}/provider

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/datasources/{name}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

POST /api/v8/remote/datasources/{name}/provider?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/datasources/{name}/provider?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/datasources/{name}/provider?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/datasources/{name}/provider?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/datasources/{name}/provider?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/datasources/{name}/provider?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/datasources/{name}/provider?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/remote/datasources/{name}/provider/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/remote/datasources/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/remote/datasources/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/remote/qorus

This REST URI path provides actions and information related to Qorus remote connections

GET /api/v8/remote/qorus

Description
Returns a list of hashes providing information for all remote connections
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of REST User and Remote Connection Hash elements
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL or OMQ::QR_READ_SERVER_CONNECTION
See also

POST /api/v8/remote/qorus

Description
Creates a new remote Qorus connection from the arguments
Arguments
This API takes the following hash arguments:
  • name (*string): the internal name of the connection
  • display_name (*string): the display name of the connection
  • short_desc (*string): the plain-text short description for the new connection
  • desc (*string): the description for the new connection with markdown formatting
  • url (string): the connection string for the new connection
Return Value
This API returns a NewConnectionInfo hash with the following keys (information about the connection created):
  • id (int): the new connection ID
  • name (string): the name of the new connection
  • display_name (string): the display name of the new connection
  • short_desc (string): the connection's description in plain text
  • desc (string): the connection's description with markdown formatting
  • info (string): a string describing the operation performed
  • action (string): the action performed
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/remote/qorus?action=list

Description
Returns a list of hashes providing information for all remote connections
See also
This API is equivalent to GET /api/remote/qorus; see that documentation for details.

PUT /api/v8/remote/qorus?action=reload

Description
Reloads all remote connections from the database
Return Value
This API returns a hash with the following key:
  • info: a string confirming the reload operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL or OMQ::QR_RELOAD_SERVER_CONNECTION

/api/v8/remote/qorus/{name}

This REST URI path provides actions and information related to a specific remote connection

DELETE /api/v8/remote/qorus/{name}

Description
Permanently deletes the current remote connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL or OMQ::QR_DELETE_SERVER_CONNECTION

GET /api/v8/remote/qorus/{name}

Description
Returns a hash information for the current remote connection
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • with_password: (optional bool) include the password in the "url" and "url_hash" keys
Return Value
This API returns a REST User and Remote Connection Hash
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL or OMQ::QR_READ_SERVER_CONNECTION

PUT /api/v8/remote/qorus/{name}

Description
Modifies the current remote Qorus connection
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: (optional string) a new description for the connection
  • url: (optional string) a new URL for the connection
  • options: (optional hash) new options for the connection; also accepts "opts" as an alias for this option
Return Value
This API returns a hash with the following key:
  • info: a string describing the connection update
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: REMOTE-CONNECTION-ERROR: invalid or unparsable "options" key
Note

POST /api/v8/remote/qorus/{name}?action=clone

Description
Clones the current connection; all parameters are optional and override the cloned connection's values. If no name is provided, then a new name is generated for the cloned connection
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the connection
  • display_name (*string): the new display name for the connection; generated from name if necessary
  • short_desc (*string): the short plain-text description for the connection
  • desc (*string): the new description for the connection with markdown formatting
  • url (*string): the new URL for the connection
  • options (*UndefinedHash): any options for the connection
Return Value
This API returns a CloneConnectionInfo hash with the following keys (a description of the new connection):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/remote/qorus/{name}?action=disable

Description
Disables current remote connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL

PUT /api/v8/remote/qorus/{name}?action=disableDebugData

Description
Disables current remote connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL

PUT /api/v8/remote/qorus/{name}?action=enable

Description
Enables current remote connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL

PUT /api/v8/remote/qorus/{name}?action=enableDebugData

Description
Enables data debugging for the current remote connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 409 Conflict: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL

GET /api/v8/remote/qorus/{name}?action=file

Description
Returns the connection as a file that can be saved

PUT /api/v8/remote/qorus/{name}?action=ping

Description
Checks connectivity to the current remote connection; if the connection was up and is monitored to be down, then any dependent interfaces will be disabled. If the connection was down and is monitored to be up, then any eligible interfaces will be reenabled.
Return Value
This API returns a hash with the following keys:
  • ok: the status of the ping
  • name: the name of the connection
  • desc: the description of the connection
  • url: the URL for the connection
  • opts: a hash of options for the connection (if any)
  • time: the elapsed time for the ping
  • info: "OK" if the ping was successful or an error message if not
  • result: a string representation of the time in seconds (ex: "0.25s")
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONNECTION_CONTROL or OMQ::QR_READ_SERVER_CONNECTION

/api/v8/remote/qorus/{name}/provider

This URI path provides access to a data provider created from a remote Qorus connection

DELETE /api/v8/remote/qorus/{name}/provider

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/qorus/{name}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

POST /api/v8/remote/qorus/{name}/provider?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/qorus/{name}/provider?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/qorus/{name}/provider?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/qorus/{name}/provider?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/qorus/{name}/provider?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/qorus/{name}/provider?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/qorus/{name}/provider?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/remote/qorus/{name}/provider/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/remote/qorus/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/remote/qorus/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/remote/user

This REST URI path provides actions and information related to Qorus user connections

GET /api/v8/remote/user

Description
Returns a list of hashes providing information for all user connections
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of REST User and Remote Connection Hash (v7) elements
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_READ_USER_CONNECTION
See also

POST /api/v8/remote/user

Description
Creates a new user connection from the arguments
Arguments
This API takes the following hash arguments:
  • name (*string): the internal name of the connection
  • display_name (*string): the display name of the connection
  • short_desc (*string): the plain-text short description for the new connection
  • desc (*string): the description for the new connection with markdown formatting
  • url (string): the connection string for the new connection
Return Value
This API returns a NewConnectionInfo hash with the following keys (information about the connection created):
  • id (int): the new connection ID
  • name (string): the name of the new connection
  • display_name (string): the display name of the new connection
  • short_desc (string): the connection's description in plain text
  • desc (string): the connection's description with markdown formatting
  • info (string): a string describing the operation performed
  • action (string): the action performed
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/remote/user?action=list

Description
Returns a list of hashes providing information for all user connections
See also
This API is equivalent to GET /api/remote/user; see that documentation for details.

PUT /api/v8/remote/user?action=reload

Description
Reloads all user connections from the database
Return Value
This API returns a hash with the following key:
  • info: a string confirming the reload operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_RELOAD_USER_CONNECTION

/api/v8/remote/user/{name}

This REST URI path provides actions and information related to a specific user connection

DELETE /api/v8/remote/user/{name}

Description
Permanently deletes the current user connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_DELETE_USER_CONNECTION

GET /api/v8/remote/user/{name}

Description
Returns a hash information for the current user connection
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • with_password: (optional bool) include the password in the "url" and "url_hash" keys
Return Value
This API returns a REST User and Remote Connection Hash (v7)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_READ_USER_CONNECTION

PUT /api/v8/remote/user/{name}

Description
Modifies the current user connection
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: (optional string) a new description for the connection
  • url: (optional string) a new URL for the connection
  • options: (optional hash) new options for the connection; also accepts "opts" as an alias for this option
  • tags: (optional hash) new tags for the connection
Return Value
This API returns a hash with the following key:
  • info: a string describing the connection update
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: USER-CONNECTION-ERROR: invalid or unparsable "options" key
Note

POST /api/v8/remote/user/{name}?action=clone

Description
Clones the current connection; all parameters are optional and override the cloned connection's values. If no name is provided, then a new name is generated for the cloned connection
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the connection
  • display_name (*string): the new display name for the connection; generated from name if necessary
  • short_desc (*string): the short plain-text description for the connection
  • desc (*string): the new description for the connection with markdown formatting
  • url (*string): the new URL for the connection
  • options (*UndefinedHash): any options for the connection
Return Value
This API returns a CloneConnectionInfo hash with the following keys (a description of the new connection):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/remote/user/{name}?action=disable

Description
Disables current user connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_MODIFY_USER_CONNECTION

PUT /api/v8/remote/user/{name}?action=disableDebugData

Description
Disables data debugging for the current user connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_MODIFY_USER_CONNECTION

PUT /api/v8/remote/user/{name}?action=enable

Description
Enables current user connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_MODIFY_USER_CONNECTION

PUT /api/v8/remote/user/{name}?action=enableDebugData

Description
Enables data debugging for the current user connection
Return Value
This API returns a hash with the following key:
  • info: a string confirming the enable operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_MODIFY_USER_CONNECTION

GET /api/v8/remote/user/{name}?action=file

Description
Returns the connection as a file that can be saved

PUT /api/v8/remote/user/{name}?action=oauth2AuthRequestUri

Description
Returns a URI for OAuth2 authorization code requests using a local URI for the initial redirect, if the oauth2_redirect_url option is set to "auto", or, if the oauth2_redirect_url option is set to "cloud" or "https://api.qoretechnologies.com/qorus-oauth2-redirect", Qore Technologies' cloud infrastructure is used for the initial redirect and the token-for-authorization-code exchange operation. A 400 Bad Request response will be returned if the connection does not require the OAuth2 authorization_code grant flow or if the oauth2_redirect_url does not have a supported value ("auto", "cloud" or "https://api.qoretechnologies.com/qorus-oauth2-redirect"). The URI string returned will use either the local Qorus server or Qore Technologies' server exchange the authorization code provided by the authorizaton server to acquire an authentication token. In case Qore Technologies' cloud services are used, the user will be redirected to the requesting Qorus instance to update the connection with the token information acquired. In both cases the user is redirected to the final redirect location after the Qorus connection has been updated with the access token information. Token information acquired by Qore Technologies' infrastructure is neither logged nor stored but only returned to the originating Qorus instance in the redirect message from https://api.qoretechnologies.com.
Arguments
This API takes the following hash arguments:
  • qorus_uri (*string): the publicly-addressable Qorus address for redirects; use this option when the Qorus server is behind a reverse proxy that changes the Host header or the SSL type
  • redirect_uri (*string): the final redirection location after the token(s) are acquired by https://api.qoretechnologies.com/qorus-oauth2-redirect and after the connection has been updated in the local Qorus instance; default: redirect to the connection in the system UI
  • response_type (*string): either "code" (the default) or "token"; the response type of the request
  • scopes (*list<string>): any scopes to include in the request; default: use the oauth2_scopes connection option value
Return Value
This API returns a value of type string: the URI string if the connection supports it, otherwise a 400 error
Errors
  • 400 Bad Request: connection does not support the OAuth2 authorization_code grant flow
  • 401 Unauthorized: no right to modify user connections
Note
Requires one of the following permissions:

PUT /api/v8/remote/user/{name}?action=ping

Description
Checks connectivity to the current user connection; if the connection was up and is monitored to be down, then any dependent interfaces will be disabled. If the connection was down and is monitored to be up, then any eligible interfaces will be reenabled.
Return Value
This API returns a hash with the following keys:
  • ok: the status of the ping
  • name: the name of the connection
  • desc: the description of the connection
  • url: the URL for the connection
  • opts: a hash of options for the connection (if any)
  • time: the elapsed time for the ping
  • info: "OK" if the ping was successful or an error message if not
  • result: a string representation of the time in seconds (ex: "0.25s")
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_READ_USER_CONNECTION

PUT /api/v8/remote/user/{name}?action=update

Description
Modifies the current user connection
See also
This API is equivalent to PUT /api/remote/user/{name}; see that documentation for details.

/api/v8/remote/user/{name}/provider

This URI path provides access to a data provider created from a user connection

DELETE /api/v8/remote/user/{name}/provider

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters for records to be deleted
  • search_options: search options
Return Value
Returns the number of records deleted
Errors
  • 400 Bad Request: returned if the request has no where_cond key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/user/{name}/provider

Description
Returns data provider information
Arguments
Return Value
This API returns a DataProviderInfo hash with the following keys (information about the current data provider):
  • name (string): the name of the data provider
  • supports_read (bool): if the data provider supports record read/search actions
  • supports_create (bool): if the data provider support record creation
  • supports_update (bool): if the data provider supports record updates
  • supports_upsert (bool): if the data provider supports record upserts / merges
  • supports_delete (bool): if the data provider supports record deletions
  • supports_native_search (bool): if the data provider supports a native record search API
  • supports_bulk_read (bool): if the data provider supports bulk record read / search actions
  • supports_bulk_create (bool): if the data provider supports bulk record creation
  • supports_bulk_upsert (bool): if the data provider supports bulk record upsert / merges
  • supports_request (bool): if the data provider supports the request/reply integration pattern (API calls)
  • supports_children (bool): if the data provider supports children
  • transaction_management (bool): if the data provider supports transaction mgmt
  • has_record (bool): if the data provider supports records
  • record_requires_search_options (bool): if the data provider requires search options when searching
  • supports_child_create (bool): if the data provider supports creating child data providers
  • supports_child_delete (bool): if the data provider supports deleting child data providers
  • supports_add_field (bool): if the data provider supports the add field API
  • supports_update_field (bool): if the data provider supports the update field API
  • supports_delete_field (bool): if the data provider supports the delete field API
  • supports_schema (bool): if the data provider supports a schema
  • supports_search_expressions (bool): if the data provider supports generic search expressions
  • supports_observable (bool): if the data provider supports the observer pattern / event API
  • supports_messages (string): if the data provider supports output messages; values are: NONE (messages not supported), SYNC (messages supported 1:1 with observed events), ASYNC (messages supported, no connection to observed events)
  • supports_connections (bool): if the data provider supports connection status reporting
  • supports_auto_reconnect (bool): if the data provider supports automtically reconnecting after lost connections
  • children_can_support_apis (bool): if the data provider can provide children that support APIs
  • children_can_support_records (bool): if the data provider can provide children that support records
  • children_can_support_observers (bool): if the data provider can provide children that support event observation
  • children_can_support_messages (bool): if the data provider can provide children that support messages
  • children_identical (bool): if child data providers are all of the same class and have the same options
  • events (*UndefinedHash): any events supported by the data provider
  • messages (*UndefinedHash): any messages supported by the data provider
  • search_logic_capabilities (int): a bitfield of supported search logic capabilities
  • mapper_keys (*UndefinedHash): a hash of mapper key information
  • desc (string): the description of the data provider
  • type (string): the type (class name) of the data provider
  • constructor_options (*UndefinedHash): any constructor options supported by the data provider
  • create_options (*UndefinedHash): any record creation options supported by the data provider
  • upsert_options (*UndefinedHash): any record upsert options supported by the data provider
  • search_options (*UndefinedHash): any record search options supported by the data provider
  • child_create_options (*UndefinedHash): any child creation options supported by the data provider
  • expressions (*UndefinedHash): any expressions supported by the data provider (for searches, for example)
  • connection_event (*string): any connection event for event-capable, connection-oriented data providers
  • disconnection_event (*string): any disconnection event for event-capable, connection-oriented data providers
  • children (*list<string>): a list of any data provider children
  • info (*UndefinedHash): optional provider-specific information
  • display_name (string): the display name of the data provider
  • short_desc (string): the short description of the data provider in plain text
  • children_can_support_transactions (bool): if the data provider can provide children that support transaction management

POST /api/v8/remote/user/{name}/provider?action=create

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • create_options: any create options supported by the data provider
Return Value
The string "OK"
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/user/{name}/provider?action=request

Arguments
  • request_options: request options
Return Value
Returns the result of the operation
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/user/{name}/provider?action=search

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • where_cond: search parameters
  • search_options: search options
Return Value
Returns a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/remote/user/{name}/provider?action=stream

Description
Returns a search stream for results corresponding to the argument(s)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • where_cond: search parameters
  • block_size: number of rows in each block (default = 1000)
Return Value
This API returns a stream consisting of a list of hashes of records matching the search parameters given by where_cond
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

POST /api/v8/remote/user/{name}/provider?action=stream

Description
Opens a stream for bulk inserting or upserting records in the data provider
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open; must be either:
    • insert: for an insert stream
    • upsert: for an upsert stream
  • upsert_options: any upsert options supported by the data provider (upsert stream only)
Return Value
This API returns a stream supporting bulk record insertion for the data provider
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/user/{name}/provider?action=update

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • set: (required) set of fields matching where_conf to update
  • where_cond: (required) search parameters
  • search_options: search options
Return Value
Returns the number of rows updated
Errors
  • 400 Bad Request: returned if the request has no set or where_cond keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/remote/user/{name}/provider?action=upsert

Arguments
This API takes the following hash argument (either as URI arguments or in the message body):
  • record: (required) the set of fields making up the new record
  • upsert_options: any upsert options supported by the data provider
Return Value
The result string of the upsert operation; see DB Provider Upsert Result Codes for possible values
Errors
  • 400 Bad Request: returned if the request has no record key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/remote/user/{name}/provider/record

This URI path provides record information for a data provider

Arguments
This URI path element is reachable only if a provider can be created from the factory; to create the provider, the following hash argument is removed from the argument list before passing onward for processing:
  • provider_options: the options to be passed to the factory creation method to create the provider

GET /api/v8/remote/user/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

PUT /api/v8/remote/user/{name}/provider/record

Description
Returns data record information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/roles

This REST URI path provides actions and information related to Qorus roles

GET /api/v8/roles

Description
Returns a list of hashes describing system roles
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Role Hash elements
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL

POST /api/v8/roles

Description
Permanently add a new role to the system
Arguments
This API takes the following hash arguments:
  • role (string): the name of the role to add
  • desc (string): the description of the role
  • perms (*list<string>): a list of permissions to add to the role; note that users must have at least the LOGIN permission to connect to the server
  • groups (*list<string>): a list of groups to add to the role
Return Value
This API returns a RoleInfo hash with the following keys (a hash of role attributes for the role added):
  • role (string): the role name
  • provider (string): the RBAC provider for the role
  • desc (string): the role's description
  • has_default (bool): if the role has the DEFAULT group, providing access to all Qorus interfaces
  • permissions (*list<string>): a list of permissions the role provides
  • groups (*list<string>): a list of interface groups the role provides access to
  • workflows (*list<RoleWorkflowInfo>): a list of workflow hashes that the group provides access to
  • services (*list<RoleServiceInfo>): a list of service hashes that the group provides access to
  • jobs (*list<RoleJobInfo>): a list of job hashes that the group provides access to
  • mappers (*list<RoleMapperInfo>): a list of mapper hashes that the group provides access to
  • vmaps (*list<RoleValueMapInfo>): a list of value map hashes that the group provides access to
  • fsms (*list<RoleFsmInfo>): a list of fsm hashes that the group provides access to
  • pipelines (*list<RolePipelineInfo>): a list of data pipeline hashes that the group provides access to
  • users (*list<string>): a list of local users that have the role; note that users in external RBAC providers (like LADP) are not listed here
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
  • 409 Conflict: role already exists
Note
Requires one of the following permissions:

GET /api/v8/roles?action=list

Description
Returns a list of hashes describing system roles
See also
This API is equivalent to GET /api/roles; see that documentation for details.

/api/v8/roles/{role}

This REST URI path provides actions and information related to a specific role

Note
Roles can only be accessed if the calling user has the OMQ::QR_USER_CONTROL permission

DELETE /api/v8/roles/{role}

Description
Deletes the current role
Arguments
Return Value
This API returns a SimpleResultInfo hash with the following key (a hash with info about the response):
  • info (string): a string describing the role deletion action
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: unknown role
Note
Requires one of the following permissions:

GET /api/v8/roles/{role}

Description
Returns a hash describing the current role
Arguments
Return Value
This API returns a RoleInfo hash with the following keys (a hash of role attributes):
  • role (string): the role name
  • provider (string): the RBAC provider for the role
  • desc (string): the role's description
  • has_default (bool): if the role has the DEFAULT group, providing access to all Qorus interfaces
  • permissions (*list<string>): a list of permissions the role provides
  • groups (*list<string>): a list of interface groups the role provides access to
  • workflows (*list<RoleWorkflowInfo>): a list of workflow hashes that the group provides access to
  • services (*list<RoleServiceInfo>): a list of service hashes that the group provides access to
  • jobs (*list<RoleJobInfo>): a list of job hashes that the group provides access to
  • mappers (*list<RoleMapperInfo>): a list of mapper hashes that the group provides access to
  • vmaps (*list<RoleValueMapInfo>): a list of value map hashes that the group provides access to
  • fsms (*list<RoleFsmInfo>): a list of fsm hashes that the group provides access to
  • pipelines (*list<RolePipelineInfo>): a list of data pipeline hashes that the group provides access to
  • users (*list<string>): a list of local users that have the role; note that users in external RBAC providers (like LADP) are not listed here
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: invalid role
Note
Requires one of the following permissions:

PUT /api/v8/roles/{role}

Description
Modifies the current role
Arguments
This API takes the following hash arguments:
  • desc (*string): updated role description
  • perms (*list<string>): if provided, this list will replace permissions for the role, unless the permission names are preceded by "+" or "-", meaning add or remove a permission from the exiting permission list, respectively (in which case all permissions must be preceded by a "+" or "-")
  • groups (*list<string>): if provided, this list will replace the group list for the role unless the group names are preceded by "+" or "-", meaning add or remove a group from the group list, respectively (in which case all group names must be preceded by a "+" or "-")
Return Value
This API returns an UpdateRoleInfo hash with the following keys (a hash with attributes updated in the role):
  • desc (*string): the new description (if provided as an argument)
  • perms (*list<string>): updated permissions (if provided as an argument)
  • groups (*list<string>): updated groups (if provided as an argument)
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
  • 404 Not Found: invalid role
Note
Requires one of the following permissions:

POST /api/v8/roles/{role}?action=clone

Description
Clones the current role to a copy with a new name and description
Arguments
This API takes the following hash arguments:
  • target (string): the name of the new cloned role
  • desc (string): the description of the new cloned role
  • perms (*list<string>): a list of new permissions for the role, if not present, permissions from the source role will be used for the new role; if present this list will define the permissions for the new role, unless the permission names are preceded by "+" or "-", meaning add or remove a permission from the source list, respectively (in which case all permissions must be preceded by a "+" or "-")
  • groups (*list<string>): a list of new interface groups, if not present, groups from the source role will be used for the new role; if present, this list will replace the source group list unless the group names are preceded by "+" or "-", meaning add or remove a group from the source list, respectively (in which case all group names must be preceded by a "+" or "-")
Return Value
This API returns a SimpleResultInfo hash with the following key (a hash with info about the response):
  • info (string): a string describing the role deletion action
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
  • 404 Not Found: invalid source role
  • 409 Conflict: target already exists
Note
Requires one of the following permissions:

PUT /api/v8/roles/{role}?action=update

Description
Modifies the current role
See also
This API is equivalent to PUT /api/roles/{role}; see that documentation for details.

/api/v8/services

This REST URI path provides actions and information related to Qorus services; the name can also be provided in the format name:version.

GET /api/v8/services

Description
Returns a list of service hashes according to the arguments passed
Arguments
This API takes the following hash arguments:
  • status (*string): one of:
    - "running": for only running services (loaded with at least one active thread)
    - "loaded": all loaded services (also running services)
    - "unloaded": only services not loaded
  • tags (*string): optional; a hash of tags to match; only workflows matching at least one of the tags will be returned; use tag=value format as the value of this option
  • tag_case_insensitive (*bool): if True then tag value comparisons are made with case-insensitive comparisons
  • tag_partial_match (*bool): if True then tag value comparisons succeed if the value given as the tag value appears anywhere in the object's tag of the same name
Return Value
This API returns a value of type *list<ServiceInfoHash>: a list of service info hashes for each accessible and matching service

POST /api/v8/services

Description
Creates a new service
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the service
  • version (string): the version of the service
  • display_name (*string): the new display name for the service; generated from name if necessary
  • short_desc (*string): the short plain-text description for the service
  • desc (*string): the new description for the service with markdown formatting
  • author (*list<string>): one or more authors of the service
  • remote (*bool): if the service should run remotely or not
  • enabled (*bool): if the service is enabled
  • class-name (*string): the class name fot the service
  • lang (*string): the language of the service
  • classes (*list<string>): classes that the service depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the service uses
  • mappers (*list<string>): mappers that the service uses
  • vmaps (*list<string>): value maps that the service uses
  • groups (*list<string>): interface groups that the service belongs to
  • tags (*UndefinedHash): user-defined tags for the service
  • config-items (*list<UndefinedHash>): config items that the service uses or defines
  • system-options (UndefinedHash): system options for the service
  • source (string): the service's source code
Return Value
This API returns a CloneServiceInfo hash with the following keys (a description of the new service):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/services?action=create

Description
Creates a new service
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the service
  • version (string): the version of the service
  • display_name (*string): the new display name for the service; generated from name if necessary
  • short_desc (*string): the short plain-text description for the service
  • desc (*string): the new description for the service with markdown formatting
  • author (*list<string>): one or more authors of the service
  • remote (*bool): if the service should run remotely or not
  • enabled (*bool): if the service is enabled
  • class-name (*string): the class name fot the service
  • lang (*string): the language of the service
  • classes (*list<string>): classes that the service depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the service uses
  • mappers (*list<string>): mappers that the service uses
  • vmaps (*list<string>): value maps that the service uses
  • groups (*list<string>): interface groups that the service belongs to
  • tags (*UndefinedHash): user-defined tags for the service
  • config-items (*list<UndefinedHash>): config items that the service uses or defines
  • system-options (UndefinedHash): system options for the service
  • source (string): the service's source code
Return Value
This API returns a CloneServiceInfo hash with the following keys (a description of the new service):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/services?action=defaultLogger

Description
Set logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/services?action=defaultLogger

Description
Returns default logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services). If set means default logger

POST /api/v8/services?action=defaultLogger

Description
Create default Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/services?action=defaultLogger

Description
Delete logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/services?action=defaultLoggerAppenders

Description
Return all logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

DELETE /api/v8/services?action=defaultLoggerAppenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/services?action=defaultLoggerAppenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/services?action=defaultLoggerAppenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/services?action=disable

Description
Disables one or more services.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more service names or IDs to disable; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes; each hash has the following keys:
  • arg: the service ID or name
  • disabled: True or False
  • [serviceid]: the service ID
  • [type]: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • [name]: the service name
  • [version]: the service version
  • info: info about the service enable action or a reason why the request failed; possible failure reasons:
    • "SERVICE-ERROR": unknown service, service not accessible
Errors
  • 409 Conflict: SERVICE-DISABLE-ERROR: missing ids argument
Note
requires permission OMQ::QR_SERVICE_CONTROL, OMQ::QR_GROUP_CONTROL, or OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

PUT /api/v8/services?action=enable

Description
Enables one or more disabled services.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more service names or IDs to enable; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes; each hash has the following keys:
  • arg: the service ID or name
  • enabled: True or False
  • [serviceid]: the service ID
  • [type]: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • [name]: the service name
  • [version]: the service version
  • info: info about the service enable action or a reason why the request failed; possible failure reasons:
    • "SERVICE-ERROR": unknown service, service not accessible
Errors
  • 409 Conflict: SERVICE-ENABLE-ERROR: missing ids argument
Note
requires permission OMQ::QR_SERVICE_CONTROL, OMQ::QR_GROUP_CONTROL, or OMQ::QR_MODIFY_GROUP, or OMQ::QR_MODIFY_GROUP_STATUS
See also

GET /api/v8/services?action=list

Description
Returns a list of services hashes according to the arguments passed.
See also
This API is equivalent to GET /api/services/{id_or_name}; see that documentation for details.

PUT /api/v8/services?action=load

Description
Loads and initializes one or more services if not already loaded.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more service names or IDs to start; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • err: True if at least one service load command failed, False if all load commands were successful
  • desc: a description of the result of the operation
  • results: a list of hashes giving the result of each load request; each hash has the following keys:
    • arg: the service ID or name (argument for the load operation)
    • loaded: a boolean giving the result of the operation
    • [already_loaded]: (only present if loaded is True) True if the service was already loaded before this call, False if loaded with this call
    • [serviceid]: the service ID
    • [type]: the type of the service; one of:
      • "system": for system services
      • "user": for user services
    • [name]: the name of the service
    • [version]: the version of the service
    • info: information abouit the operation; if the operation failed, a formatted error string will appear here; possible failure reasons:
      • "SERVICE-ERROR": the given service cannot be loaded (does not exist, error initializing the service)
      • "SERVICE-ACCESS-ERROR": the user does not have the right to access the given service (for more information, see Interface Groups, only possible if Role Based Access Control is enabled)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_CALL_SYSTEM_SERVICES_RW or OMQ::QR_CALL_SYSTEM_SERVICES_RO for system services, OMQ::QR_CALL_USER_SERVICES_RW or OMQ::QR_CALL_USER_SERVICES_RO for user services
See also

PUT /api/v8/services?action=reset

Description
Resets one or more services and reloads them from the database.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more service names or IDs to reload; a comma-separated string will be split into a list
  • load: (optional) will be evaluated with Qore::parse_boolean(); if True then services not already loaded will be loaded with this call; default @ref False, meaning that services not already loaded will not be loaded by this call
Return Value
This API returns a list of hashes giving the result of each reset request; each hash has the following keys:
  • arg: the service ID or name (argument for the load operation)
  • [loaded]: True if the service was already loaded before this call, False if loaded with this call
  • [reset]: True if the service was (re)loaded
  • [serviceid]: the service ID
  • [type]: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • [name]: the name of the service
  • [version]: the version of the service
  • info: information abouit the operation; if the operation failed, a formatted error string will appear here; possible failure reasons:
    • "SERVICE-ERROR": the given service cannot be loaded (does not exist, error initializing the service)
    • "SERVICE-ACCESS-ERROR": the user does not have the right to access the given service (for more information, see Interface Groups, only possible if Role Based Access Control is enabled)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SERVICE-RESET-ERROR: missing ids argument
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also

PUT /api/v8/services?action=resetAll

Description
Unloads all accessible services currently loaded in memory and reloads them from the database. If the calling user has restricted access to user services, only services visible by the current user are reset
Return Value
This API returns a list of hashes listing all services reset; each hash has the following keys:
  • type: the type of service reset; one of:
    • "system": for system services
    • "user": for user services
  • name: name of the service
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also

PUT /api/v8/services?action=resetSystem

Description
Unloads all system services currently loaded in memory and reloads them from the database.
Return Value
This API returns a list of hashes listing all services reset; each hash has the following keys:
  • type: the type of service reset; always "system" for this call
  • name: name of the service
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also

PUT /api/v8/services?action=resetUser

Description
Unloads all accessible user services currently loaded in memory and reloads them from the database. If the calling user has restricted access to user services, only services visible by the current user are reset
Return Value
This API returns a list of hashes listing all services reset; each hash has the following keys:
  • type: the type of service reset; always "user" for this call
  • name: name of the service
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE
See also

PUT /api/v8/services?action=unload

Description
Unloads one or more services from the system. If the service is running, then it is first stopped. Additionally, for each service to be unloaded, any outstanding method calls must return before the service can be unloaded.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more service names or IDs to unload; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes giving the result of each unload request; each hash has the following keys:
  • arg: the service ID or name (argument for the unload operation)
  • [loaded]: True if the service was already loaded, False if not
  • [unloaded]: True if the service was unloaded, False if not
  • [serviceid]: the service ID
  • [type]: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • [name]: the name of the service
  • [version]: the version of the service
  • info: information abouit the operation; if the operation failed, a formatted error string will appear here; possible failure reasons:
    • "SERVICE-ERROR": the given service cannot be loaded (does not exist, error initializing the service)
    • "SERVICE-ACCESS-ERROR": the user does not have the right to access the given service (for more information, see Interface Groups, only possible if Role Based Access Control is enabled)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SERVICE-UNLOAD-ERROR: missing ids argument
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_UNLOAD_SERVICE
See also

/api/v8/services/{id_or_name}

This REST URI path provides actions and information related to Qorus services.

DELETE /api/v8/services/{id_or_name}

Description
Deletes the current service
Arguments
Return Value
This API returns a ServiceDeletionResult hash with the following keys (service deletion info):
  • type (string): the type of the service deleted
  • name (string): the name of the service deleted
  • version (string): the version of the service deleted
  • serviceid (string): the ID of the service deleted
Errors
  • 400 Bad Request: cannot delete system services
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such service
Note
Requires one of the following permissions:

GET /api/v8/services/{id_or_name}

Description
Returns information about the current service
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a hash describing the service with the following keys:
  • alerts: a list of alerts raised against the service; each list element is a REST Alert Hash (may be empty)
  • author: the author of the service (if any)
  • autostart: a boolean value indicating if the service should be autostarted or not
  • connections: a list of connection objects that this service depends on; each list element is a REST Connection Dependency Hash (may be empty)
  • created: the date/time the service was created
  • description: the description of the service (if any)
  • enabled: a boolean flag indicating if the service is enabled or not; disabled services cannot be loaded
  • groups: a list of interface groups that the service belongs to; each list element is a REST Interface Group Hash (may be empty)
  • latest: a boolean flag indicating if the current contextual service is the latest service of its type and name
  • log_url: a complete URL to the websocket source for the service log
  • mappers: a list of mappers associated with the service (can be NOTHING); each mapper element is a REST Mapper Hash
  • manual_autostart: a boolean flag set if the autostart value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • methods: a list of REST Service Method Hash elements
  • modified: the date/time the service was last modified
  • name: the name of the service
  • options: a hash of options set on the service
  • parse_options: a list of symbolic parse options for the service program container
  • processes: a list of hashes of process information, in case the service is running remotely in one or more a qsvc processes
  • remote: a boolean value indicating if the service is run as an external process or not
  • resource_files: a list of resource file hashes (if any); each list element is a hash with the following keys:
    • name: the name of the resource
    • type: the type code for the resource
  • resources: a REST Service Resource Hash
  • serviceid: the service ID
  • status: the status of the service; one of:
    • "loaded": loaded but not running
    • "running": loaded and running with at least one service thread
    • "unloaded": not loaded
  • state: a hash of saved service state data (if any); see svc_save_state_data() for more info
  • stateless: True if the service is a stateless service, False if not
  • threads: the number of threads running in the service
  • type: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • version: the version of the service
  • vmaps: a list of value maps associated with the service (can be NOTHING); each value map element is a REST Value Map Hash

PUT /api/v8/services/{id_or_name}

Description
Updates the current service
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the service
  • version (*string): the version of the service
  • display_name (*string): the new display name for the service; generated from name if necessary
  • short_desc (*string): the short plain-text description for the service
  • desc (*string): the new description for the service with markdown formatting
  • author (*list<string>): one or more authors of the service
  • remote (*bool): if the service should run remotely or not
  • enabled (*bool): if the service is enabled
  • class-name (*string): the class name fot the service
  • lang (*string): the language of the service
  • classes (*list<string>): classes that the service depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the service uses
  • mappers (*list<string>): mappers that the service uses
  • vmaps (*list<string>): value maps that the service uses
  • groups (*list<string>): interface groups that the service belongs to
  • tags (*UndefinedHash): user-defined tags for the service
  • config-items (*list<UndefinedHash>): config items that the service uses or defines
  • system-options (UndefinedHash): system options for the service
  • source (*string): the service's source code
Return Value
This API returns an UpdateServiceInfo hash with the following keys (a description of the new service):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/services/{id_or_name}?action=clone

Description
Clones the current service; all parameters are optional and override the cloned service's values. If no name is provided, then a new name is generated for the cloned service
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the service
  • version (*string): the version of the service
  • display_name (*string): the new display name for the service; generated from name if necessary
  • short_desc (*string): the short plain-text description for the service
  • desc (*string): the new description for the service with markdown formatting
  • author (*list<string>): one or more authors of the service
  • remote (*bool): if the service should run remotely or not
  • enabled (*bool): if the service is enabled
  • class-name (*string): the class name fot the service
  • lang (*string): the language of the service
  • classes (*list<string>): classes that the service depends on and requires
  • fsms (*list<UndefinedHash>): Finite State Machines / Flow Designer (fsms) that the service uses
  • mappers (*list<string>): mappers that the service uses
  • vmaps (*list<string>): value maps that the service uses
  • groups (*list<string>): interface groups that the service belongs to
  • tags (*UndefinedHash): user-defined tags for the service
  • config-items (*list<UndefinedHash>): config items that the service uses or defines
  • system-options (UndefinedHash): system options for the service
  • source (*string): the service's source code
Return Value
This API returns a CloneServiceInfo hash with the following keys (a description of the new service):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/services/{id_or_name}?action=disable

Description
Disables the current service.
Return Value
This API returns a hash with the following keys:
  • type: the service type one of:
    • "system": for system services
    • "user": for user services
  • name: the service name
  • version: the service version
  • serviceid: the service ID
  • info: info about the service disable action
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

PUT /api/v8/services/{id_or_name}?action=enable

Description
Enables the current service if it is disabled.
Return Value
This API returns a hash with the following keys:
  • type: the service type one of:
    • "system": for system services
    • "user": for user services
  • name: the service name
  • version: the service version
  • serviceid: the service ID
  • info: info about the service enable action
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

GET /api/v8/services/{id_or_name}?action=file

Description
Returns the service as a file that can be saved

PUT /api/v8/services/{id_or_name}?action=init

Description
Loads and initializes the current service if it is not already loaded.
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 409 Conflict: SERVICE-ERROR: the given service cannot be loaded (error initializing the service)
Note

POST /api/v8/services/{id_or_name}?action=kill

Description
Kills a remote service cluster process
Return Value
This API returns a hash with the following keys:
  • status: "OK", "ERR" if not
  • code: the return code of the kill() command: 0 if successful, non-zero if not
Errors
  • 404 Not Found: this response is returned if no process is running for the current service
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/services/{id_or_name}?action=load

Description
Loads and initializes the current service if it is not already loaded.
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 409 Conflict: SERVICE-ERROR: the given service cannot be loaded (error initializing the service)
Note

GET /api/v8/services/{id_or_name}?action=options

Description
Returns options set on the current service.
Return Value
This API returns NOTHING if no options are set, otherwise a hash of service options.

PUT /api/v8/services/{id_or_name}?action=reset

Description
Unloads the current service (if loaded) and reloads it from the database.
Return Value
This API returns True if the service was already loaded before this call, False if not
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_RESET_SERVICE

PUT /api/v8/services/{id_or_name}?action=resourceLimits

Description
Sets scaling parameters for stateless services; this API can only be used when Qorus is running in Kubernetes.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • scaling-min-replicas
  • scaling-max-replicas
  • scaling-cpu
  • scaling-memory
Return Value
This API returns the response of the Kubernetes REST request after updating the horizontal pod autoscaler.
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SCALING
Errors
  • 400 Bad Request: returned if Qorus is not running under Kubernetes, the service is not stateless. or no arguments provided
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

PUT /api/v8/services/{id_or_name}?action=scaling

Description
Sets scaling parameters for stateless services; this API can only be used when Qorus is running in Kubernetes.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • scaling-min-replicas
  • scaling-max-replicas
  • scaling-cpu
  • scaling-memory
Return Value
This API returns the response of the Kubernetes REST request after updating the horizontal pod autoscaler.
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SCALING
Errors
  • 400 Bad Request: returned if Qorus is not running under Kubernetes, the service is not stateless. or no arguments provided
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

PUT /api/v8/services/{id_or_name}?action=setAutostart

Description
Sets the autostart status of the current service
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • autostart: (required) the autostart status for the service (parsed with parse_boolean())
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "autostart" hash argument
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL or OMQ::QR_SET_SERVICE_AUTOSTART

PUT /api/v8/services/{id_or_name}?action=setOptions

Description
Sets options for the current service. If the service has an option list and any of the options are not valid for that service, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options to set against the service; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SERVICE-OPTION-ERROR: invalid option for service or option cannot be overridden at the service level
Note

PUT /api/v8/services/{id_or_name}?action=setRemote

Description
Sets the remote value for the current service.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • remote: (required) parsed with Qore::parse_boolean(); a boolean value giving the new remote value for the service
Return Value
This API returns a hash with the following keys:
  • updated: True or False
  • remote: the new remote value
  • info: info about the service update action
Errors
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SERVICE-SETREMOTE-ERROR: missing remote argument; cannot update the remote value to True on system services
Note
  • requires permission OMQ::QR_SERVICE_CONTROL
  • services that have their remote value changed are temporarily disabled and then reenabled after the change

PUT /api/v8/services/{id_or_name}?action=setStateData

Description
Provides an API for externally updating service state data
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • data: a hash of new service state data or NOTHING which will clear any data
Return Value
This API returns the new data or NOTHING if the data is cleared
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note
requires permission OMQ::QR_SERVICE_CONTROL
See also
  • svc_get_state_data()
  • svc_save_state_data()

PUT /api/v8/services/{id_or_name}?action=start

Description
Loads and initializes the current service if it is not already loaded.
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 409 Conflict: SERVICE-ERROR: the given service cannot be loaded (error initializing the service)
Note

PUT /api/v8/services/{id_or_name}?action=stop

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

Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 409 Conflict: SERVICE-NOT-LOADED: this exception is thrown when the service is not loaded
Note

DELETE /api/v8/services/{id_or_name}?action=stream

Description
Opens a DELETE stream for the named stream if the service implements that stream.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open
Return Value
See documentation for the stream implemented by the service.

POST /api/v8/services/{id_or_name}?action=stream

Description
Opens a POST stream for the named stream if the service implements that stream.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open
Return Value
See documentation for the stream implemented by the service.

PUT /api/v8/services/{id_or_name}?action=stream

Description
Opens a PUT stream for the named stream if the service implements that stream.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open
Return Value
See documentation for the stream implemented by the service.

GET /api/v8/services/{id_or_name}?action=stream

Description
Opens a GET stream for the named stream if the service implements that stream.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stream: (required) the name of the stream to open
Return Value
See documentation for the stream implemented by the service.

PUT /api/v8/services/{id_or_name}?action=unload

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

Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
  • 409 Conflict: SERVICE-NOT-LOADED: this exception is thrown when the service is not loaded
Note

/api/v8/services/{id_or_name}/authlabels

This REST URI path provides actions and information for system functionality

GET /api/v8/services/{id_or_name}/authlabels

Description
Gets list of authentication labels associated wth the service
Return Value
Returns hash of labels and their values

PUT /api/v8/services/{id_or_name}/authlabels

Description

Updates authentication labels associated wth the service

Input Value
Hash with label names and their values where keys are authentication labels and values have one of the following two values:
  • "default": default Qorus authentication is used
  • "permissive": all requests are accepted with no authentication necessary
Return Value
String "OK" representing the authentication labels were updated successfully
Errors
In case of any error, HTTP status 409 is returned and standard Qorus error hash is retuned in response body

/api/v8/services/{id_or_name}/config

This REST URI path provides actions and information related to Qorus service configuration items

GET /api/v8/services/{id_or_name}/config

Description
Returns a list of service configuration items for the service
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:1") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

GET /api/v8/services/{id_or_name}/config?action=yaml

Description
Returns a list of service configuration items for the service as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:1") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/services/{id_or_name}/config/{name}

This REST URI path provides actions and information related to a particular Qorus. Prefix can be passed within the config item name or as following: /v3/services/{id_or_name}/config/{name}?prefix={prefix}. service configuration item

DELETE /api/v8/services/{id_or_name}/config/{name}

Description
Permanently deletes the current value for the configuration item on this service level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/services/{id_or_name}/config/{name}

Description
Returns a hash for the current service configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "service:1", "service:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

PUT /api/v8/services/{id_or_name}/config/{name}

Description
Sets the value for the given service configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

PUT /api/v8/services/{id_or_name}/config/{name}?action=yaml

Description
Sets the value for the given service configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)
Note

GET /api/v8/services/{id_or_name}/config/{name}?action=yaml

Description
Returns a hash for the current service configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (serialized YAML string) the default value of the configuration item
  • "value": (serialized YAML string) the current value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": (serialized YAML string) the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "service:1", "service:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

DELETE /api/v8/services/{id_or_name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on this service level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/services/{id_or_name}/methods

This REST URI path provides actions and information related to Qorus service methods for a given service.

GET /api/v8/services/{id_or_name}/methods

Description
Returns information about service methods for the given service
Return Value
This API returns a list of REST Service Method Hash elements
Errors
  • 403 Forbidden: SERVICE-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given service (for more information, see Interface Groups)

/api/v8/services/{id_or_name}/resource_files

This REST URI path provides information about service resource files.

GET /api/v8/services/{id_or_name}/resource_files

Return Value
Returns a hash of service resource information; the keys are the resource name, the values hashes with the following keys:
  • type: the type code for the service resource

/api/v8/services/{id_or_name}/resource_files/{name}

This REST URI path provides information about a particular service resource file.

GET /api/v8/services/{id_or_name}/resource_files/{name}

Return Value
Returns a hash of service resource file information with the following keys:
  • type: the type code for the service resource
  • data: the data of the service resource

GET /api/v8/services/{id_or_name}/resource_files/{name}?action=download

Return Value
Returns the service resource file data requested with the Content-Type as the file's MIME type

/api/v8/services/{id_or_name}/{method}

This REST path provides actions and information about service methods

GET /api/v8/services/{id_or_name}/{method}

Return Value
This API returns a REST Service Method Hash describing the service method with the addition of the following keys describing the service:
  • service_status: the status of the service; one of:
    • "loaded": loaded but not running
    • "running": loaded and running with at least one service thread
    • "unloaded": not loaded
  • serviceid: the ID of the service
  • service_name: the name of the service
  • service_type: the type of the service; one of:
    • "system": for system services
    • "user": for user services

PUT /api/v8/services/{id_or_name}/{method}?action=call

Description
Calls the current service method with any argument given and returns the result; the service is loaded and started if necessary.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the method arguments; parse_args takes precedence over args
  • [args]: any arguments passed here will be used directly as the method arguments
Return Value
This API returns result of calling the current service method
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SERVICE-ERROR: invalid method call; missing method name
Note
requires permission OMQ::QR_CALL_SYSTEM_SERVICES_RW (for methods with the write flag set) or OMQ::QR_CALL_SYSTEM_SERVICES_RO for system services, OMQ::QR_CALL_USER_SERVICES_RW (for methods with the write flag set) or OMQ::QR_CALL_USER_SERVICES_RO for user services

/api/v8/slas

This REST URI path provides actions and information about Qorus SLAs

GET /api/v8/slas

Description
Returns information about SLAs to the calling user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then a list of hashes is returned, one element for each SLA; each hash in the returned list represents an SLA as a OMQ::SlaInfo hash

POST /api/v8/slas

Description
Creates a system SLA according to the arguments
Arguments
This API takes the following hash arguments:
  • name (string): the unique name of the SLA
  • display_name (*string): the new display name for the SLA; generated from name if necessary
  • short_desc (*string): the short plain-text description for the SLA
  • description (string): the description of the SLA with markdown formatting
  • units (*string): describes the meaning of SLA event values (allowed values: "seconds" and "other"; default: "seconds")
  • methods (*list<ServiceSlaInfo>): list of methods to attach to the SLA
  • jobs (*list<string>): jobs to attach to the SLA
Return Value
This API returns a SlaInfo hash with the following keys (hash of the SLA created or of the existing SLA if all arguments match an existing SLA exactly):
  • slaid (int): the ID of the SLA
  • name (string): the unique name of the SLA
  • display_name (*string): the display name of the SLA
  • short_desc (*string): the short description of the SLA
  • description (string): the description of the SLA
  • units (string): describes the meaning of SLA event values (allowed values: "seconds" and "other")
  • methods (*list<SlaServicveMethodInfo>): list of service methods with the SLA
  • jobs (*list<SlaJobInfo>): list of jobs with the SLA
Errors
  • 400 Bad Request: the given SLA name already exists; invalid or missing argument
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

POST /api/v8/slas?action=create

Description
Creates a new SLA
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the SLA
  • display_name (*string): the new display name for the SLA; generated from name if necessary
  • short_desc (*string): the short plain-text description for the SLA
  • desc (string): the new description for the SLA with markdown formatting
  • units (*string): describes the units of SLA event values (allowed values: "seconds" and "other")
  • methods (*list<ServiceSlaInfo>): list of methods to attach to the SLA
  • jobs (*list<string>): jobs to attach to the SLA
Return Value
This API returns a CreateSlaInfo hash with the following keys (a description of the new type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/slas?action=events

Description
Returns a list of SLA events matching the search arguments; the archive schema is also searched if fewer than the maximum number of results is found in the main schema.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: return the results in descending order
  • err: the error string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • errdesc: the error description string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • name: the name of the SLA; can be a list of names or a string with "%" characters for SQL like matching
  • limit: max number of rows to return, if not given, then the value of the "row-limit" option is used (default: 100)
  • mindate: minimum SLA event timestamp (inclusive, meaning ">=" comparisons used)
  • maxdate: maximum SLA event timestamp (exclusive, meaning "<" comparisons used)
  • offset: row offset
  • producer: the producer string of SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • slaid: the SLA ID, can be a list of IDs
  • sort: columns for sorting the results
  • success: filter for sucessful calls (1) or errored calls (0)
Return Value
A list of hashes is returned, one element for each matching SLA event; each element in the returned list is an OMQ::SlaEventInfo hash

POST /api/v8/slas?action=flush

Description
Flushes all SLA event information to persistent storage
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/slas?action=performance

Description
Returns a list of SLA events matching the search arguments; the archive schema is also searched if fewer than the maximum number of results is found in the main schema.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • err: the error string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • errdesc: the error description string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • grouping: (optional) possible values for reporting performance statistics:
    • "hourly": hourly grouping
    • "daily": daily grouping
    • "monthly": monthly grouping
    • "yearly": yearly grouping
  • name: the name of the SLA; can be a list of names or a string with "%" characters for SQL like matching
  • maxdate: maximum SLA event timestamp (exclusive, meaning "<" comparisons used)
  • mindate: minimum SLA event timestamp (inclusive, meaning ">=" comparisons used)
  • producer: the producer string of SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • slaid: the SLA ID, can be a list of IDs
  • success: filter for sucessful calls (1) or errored calls (0)
Returns
an empty list if no events are matched, otherwise a list of OMQ::SlaPerformanceInfo hashes

/api/v8/slas/{sla}

This REST URI path provides actions and information about a particular Qorus SLA

DELETE /api/v8/slas/{sla}

Description
Deletes the SLA from the system
Arguments
Return Value
This API returns a DeleteSlaInfo hash with the following keys (hash of the SLA deleted):
  • slaid (int): the ID of the SLA
  • name (string): the name of the SLA
  • display_name (*string): the display name of the SLA
  • short_desc (*string): the short description of the SLA
  • description (string): the description of the SLA
  • units (string): describes the meaning of SLA event values (allowed values: "seconds" and "other")
  • methods (*list<SlaServicveMethodInfo>): list of service methods with the SLA
  • jobs (*list<SlaJobInfo>): list of jobs with the SLA
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

GET /api/v8/slas/{sla}

Description
Returns information about the SLA to the calling user.
Return Value
A OMQ::SlaInfo hash of the SLA

PUT /api/v8/slas/{sla}

Description
Updates the current SLA
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the SLA
  • display_name (*string): the new display name for the SLA; generated from name if necessary
  • short_desc (*string): the short plain-text description for the SLA
  • desc (*string): the new description for the SLA with markdown formatting
  • units (*string): describes the units of SLA event values (allowed values: "seconds" and "other")
  • methods (*list<ServiceSlaInfo>): list of methods to attach to the SLA
  • jobs (*list<string>): jobs to attach to the SLA
Return Value
This API returns an UpdateSlaInfo hash with the following keys (a description of the new SLA):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/slas/{sla}?action=clone

Description
Clones the current SLA; all parameters are optional and override the cloned SLA's values. If no name is provided, then a new name is generated for the cloned SLA
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the SLA
  • display_name (*string): the new display name for the SLA; generated from name if necessary
  • short_desc (*string): the short plain-text description for the SLA
  • desc (*string): the new description for the SLA with markdown formatting
  • units (*string): describes the units of SLA event values (allowed values: "seconds" and "other")
  • methods (*list<ServiceSlaInfo>): list of methods to attach to the SLA
  • jobs (*list<string>): jobs to attach to the SLA
Return Value
This API returns a CloneSlaInfo hash with the following keys (a description of the new SLA):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/slas/{sla}?action=error

Description
Posts an error event for the SLA
Arguments
This API takes the following hash arguments:
  • value (number): the event value
  • err (string): the error code
  • desc (string): the error description
Return Value
This API returns a value of type bool: True if the event was posted
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

GET /api/v8/slas/{sla}?action=events

Description
Returns a list of SLA events matching the search arguments; the archive schema is also searched if fewer than the maximum number of results is found in the main schema.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: return the results in descending order
  • err: the error string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • errdesc: the error description string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • limit: max number of rows to return, if not given, then the value of the "row-limit" option is used (default: 100)
  • mindate: minimum SLA event timestamp (inclusive, meaning ">=" comparisons used)
  • maxdate: maximum SLA event timestamp (exclusive, meaning "<" comparisons used)
  • offset: row offset
  • producer: the producer string of SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • sort: columns for sorting the results
Return Value
A list of hashes is returned, one element for each matching SLA event; each element in the returned list is an OMQ::SlaEventInfo hash

GET /api/v8/slas/{sla}?action=file

Description
Returns the SLA as a file that can be saved

GET /api/v8/slas/{sla}?action=performance

Description
Returns a list of SLA events matching the search arguments; the archive schema is also searched if fewer than the maximum number of results is found in the main schema.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • err: the error string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • errdesc: the error description string of unsucessful SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • grouping: (optional) possible values for reporting performance statistics:
    • "hourly": hourly grouping
    • "daily": daily grouping
    • "monthly": monthly grouping
    • "yearly": yearly grouping
  • maxdate: maximum SLA event timestamp (exclusive, meaning "<" comparisons used)
  • mindate: minimum SLA event timestamp (inclusive, meaning ">=" comparisons used)
  • producer: the producer string of SLA events; can be a list of strings or a string with "%" characters for SQL like matching
  • success: filter for sucessful calls (1) or errored calls (0)
Returns
an empty list if no events are matched, otherwise a list of OMQ::SlaPerformanceInfo hashes

PUT /api/v8/slas/{sla}?action=removeJob

Description
Removes the current SLA from the job specified with the required arguments (if associated).
Arguments
This API takes the following required hash argument (either as a URI argument or in the message body):
  • job (string): the name of the job
Return Value
A hash with the following keys is returned:
  • job (string): the name of the job
  • slaid (int): the SLA ID set on the given job
  • removed (bool): True if removed, False if not (not associated)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_MODIFY_SLA or OMQ::QR_SLA_CONTROL

PUT /api/v8/slas/{sla}?action=removeMethod

Description
Removes the current SLA from the user service method specified with the required arguments (if associated).
Arguments
This API takes the following required hash arguments (either as URI arguments or in the message body):
  • service (string): the name of the user service
  • method (string): the name of the service method
Return Value
A hash with the following keys is returned:
  • service (string): the name of the user service
  • method (string): the name of the service method
  • slaid (int): the current SLA ID
  • removed (bool): True if removed, False if not (not associated)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_MODIFY_SLA or OMQ::QR_SLA_CONTROL

PUT /api/v8/slas/{sla}?action=setJob

Description
Sets the current SLA against the job specified with the required arguments; after this call, job instance execution will be tracked with success and failure and call times.
Arguments
This API takes the following required hash argument (either as a URI argument or in the message body):
  • job (string): the name of the job
Return Value
A hash with the following keys is returned:
  • job (string): the name of the job
  • slaid (int): the SLA ID set on the given job
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_MODIFY_SLA or OMQ::QR_SLA_CONTROL

PUT /api/v8/slas/{sla}?action=setMethod

Description
Sets the current SLA against the user service method specified with the required arguments; after this call, user service calls to the specified method will be tracked with success and failure and call times.
Arguments
This API takes the following required hash arguments (either as URI arguments or in the message body):
  • service (string): the name of the user service
  • method (string): the name of the service method
Return Value
A hash with the following keys is returned:
  • service (string): the name of the user service
  • method (string): the name of the service method
  • slaid (int): the SLA ID set on the given user service method
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_MODIFY_SLA or OMQ::QR_SLA_CONTROL

POST /api/v8/slas/{sla}?action=success

Description
Posts a success event for the SLA
Arguments
This API takes the following hash argument:
  • value (number): the event value
Return Value
This API returns a value of type bool: True if the event was posted
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled, and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

/api/v8/slas

This REST URI path provides actions and information about Qorus SLAs

/api/v8/steps

This REST API path provides actions and information about specific workflow steps

GET /api/v8/steps

Description
Returns a list of hashes of all steps
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a list of REST Step Hash V3 elements (if neither list nor short options are passed as above).

POST /api/v8/steps

Description
Creates a new step
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the step
  • display_name (*string): the new display name for the step; generated from name if necessary
  • short_desc (*string): the short plain-text description for the step
  • desc (*string): the new description for the step with markdown formatting
  • version (string): the new version for the step
  • author (*string): the author of the step
  • code (string): the source code for the step
  • base_class_name (*string): the base class name for the step
  • language (*string): the programming language of the step
  • config_items (*list<UndefinedHash>): a list of config items for the step
  • class_name (string): the class name for the step; must be a valid identifier
Return Value
This API returns a CreateStepInfo hash with the following keys (a description of the new step):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/steps?action=create

Description
Creates a new step
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the step
  • display_name (*string): the new display name for the step; generated from name if necessary
  • short_desc (*string): the short plain-text description for the step
  • desc (*string): the new description for the step with markdown formatting
  • version (string): the new version for the step
  • author (*string): the author of the step
  • code (string): the source code for the step
  • base_class_name (*string): the base class name for the step
  • language (*string): the programming language of the step
  • config_items (*list<UndefinedHash>): a list of config items for the step
  • class_name (string): the class name for the step; must be a valid identifier
Return Value
This API returns a CreateStepInfo hash with the following keys (a description of the new step):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/steps?action=list

Description
Identical to GET /api/steps
See also
GET /api/steps

/api/v8/steps/{id_or_name}

This REST API path provides actions and information about specific workflow steps

DELETE /api/v8/steps/{id_or_name}

Description
Deletes the step
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a StepDeletionInfo hash with the following key (information about the step that was deleted):
  • id (int): the ID of the step that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such function
Note
Requires one of the following permissions:

GET /api/v8/steps/{id_or_name}

Description

Returns a hash of information about the current step.

Return Value
This API returns a REST Step Hash providing about the current step plus additional keys as follows:
  • functions: if the step is a class step with step functions, this element is returned as a list of REST Function Hash elements with the following additional key:
  • class: if the step is a new-style step implemented by a single class, then this element is returned as a REST Class Hash
  • desc: the step description
  • config: a hash of step configuration item information keyed by configuration item and with hash values with the following keys:
    • "name": the name of the configuration item
    • "prefix": the prefix of the configuration item
    • "type": the type of the configuration item
    • "desc": the description of the configuration item
    • "default_value": the default value of the configuration item
    • "strictly_local": if the configuration item is defined strictly on local level
    • "config_group": the group of the configuration item
    • "allowed_values": the list of allowed values for the configuration item if defined

PUT /api/v8/steps/{id_or_name}

Description
Updates the current step
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the step
  • display_name (*string): the new display name for the step; generated from name if necessary
  • short_desc (*string): the short plain-text description for the step
  • desc (*string): the new description for the step with markdown formatting
  • version (*string): the new version for the step
  • author (*string): the author of the step
  • code (*string): the source code for the step
  • base_class_name (*string): the base class name for the step
  • language (*string): the programming language of the step
  • config_items (*list<UndefinedHash>): a list of config items for the step
  • class_name (*string): the class name for the step; must be a valid identifier
Return Value
This API returns an UpdateStepInfo hash with the following keys (a description of the step):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/steps/{id_or_name}?action=clone

Description
Clones the current step; all parameters are optional and override the cloned step's values. If no version is provided, then the current version is incremented in the cloned step; if a version but no name is provided, then a new name is generated for the cloned step
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the step
  • display_name (*string): the new display name for the step; generated from name if necessary
  • short_desc (*string): the short plain-text description for the step
  • desc (*string): the new description for the step with markdown formatting
  • version (*string): the new version for the step
  • author (*string): the author of the step
  • code (*string): the source code for the step
  • base_class_name (*string): the base class name for the step
  • language (*string): the programming language of the step
  • config_items (*list<UndefinedHash>): a list of config items for the step
  • class_name (*string): the class name for the step; must be a valid identifier
Return Value
This API returns a CloneStepInfo hash with the following keys (a description of the new step):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/steps/{id_or_name}?action=file

Description
Returns the step as a file that can be saved

/api/v8/steps/{id_or_name}/config

This REST URI path provides actions and information related to Qorus step configuration items

GET /api/v8/steps/{id_or_name}/config

Description
Returns a list of step configuration items for the step
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined Note: to obtain values the workflows/{id_or_name}/stepinfo/{id_or_name}/config REST API should be used

GET /api/v8/steps/{id_or_name}/config?action=yaml

Description
Returns a list of step configuration items for the step as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string) Note: to obtain value the workflows/{id_or_name}/stepinfo/{id_or_name}/config REST API should be used

/api/v8/steps/{id_or_name}/config/{name}

This REST URI path provides actions and information related to a particular Qorus. Prefix can be passed within the config item name or as following: /v3/steps/{id_or_name}/config/{name}?prefix={prefix}. step configuration item

DELETE /api/v8/steps/{id_or_name}/config/{name}

Description
Permanently deletes the current value for the configuration item on this step level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/steps/{id_or_name}/config/{name}

Description
Returns a hash for the current step configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined Note: to obtain value the workflows/{id_or_name}/stepinfo/{id_or_name}/config REST API should be used

PUT /api/v8/steps/{id_or_name}/config/{name}

Description
Sets the value for the given step configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/steps/{id_or_name}/config/{name}?action=yaml

Description
Sets the value for the given step configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value (YAML-serialized string): the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/steps/{id_or_name}/config/{name}?action=yaml

Description
Returns a hash for the current step configuration item as a YAML-serialized string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string) Note: to obtain value the workflows/{id_or_name}/stepinfo/{id_or_name}/config REST API should be used

DELETE /api/v8/steps/{id_or_name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on this step level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/sync-events

This REST URI path provides actions and information about workflow synchronization events

GET /api/v8/sync-events

Description
Returns a list of hashes of information about workflow synchronization event types
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of workflow synchronization event names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings with workflow synchronization event names and brief info is returned
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Synchronization Event Type Hash elements

POST /api/v8/sync-events

Description
Creates a new workflow synchronization event type
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow synchronization event type
  • desc (string): the new description for the workflow synchronization event type with markdown formatting
Return Value
This API returns a CreateWorkflowSyncEventInfo hash with the following keys (a description of the new workflow synchronization event type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/sync-events?action=create

Description
Creates a new workflow synchronization event type
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow synchronization event type
  • desc (string): the new description for the workflow synchronization event type with markdown formatting
Return Value
This API returns a CreateWorkflowSyncEventInfo hash with the following keys (a description of the new workflow synchronization event type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/sync-events?action=events

Description
Returns a hash of information about the current workflow synchronization event type
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: parsed with Qore::parse_boolean(); if True, return in descending order
  • eventkey: the event key value
  • eventname: the event type name
  • id: one or more event type IDs
  • limit: max number of rows to return
  • maxmodified: if present, parsed as a date; maximum modified date
  • modified: if present, parsed as a date; minimum modified date
  • offset: row offset
  • posted: the event posted status (True or False)
  • sort: a comma-separated string will be split into a list;columns for sorting the results
Return Value
This API returns a list of REST Workflow Synchronization Event Type Hash elements
See also

/api/v8/sync-events/{type}

This REST URI path provides actions and information about workflow synchronization event types

DELETE /api/v8/sync-events/{type}

Description
Deletes the workflow synchronization event type
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a SyncEventDeletionInfo hash with the following key (information about the event that was deleted):
  • id (int): the ID of the workflow synchronization event type that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such workflow synchronization event type
Note
Requires one of the following permissions:

GET /api/v8/sync-events/{type}

Description
Returns a hash of information about the current workflow synchronization event type
Return Value
This API returns a REST Workflow Synchronization Event Type Hash

PUT /api/v8/sync-events/{type}

Description
Updates the current workflow synchronization event type
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the event type; if not provided, the new name will be generated
  • desc (*string): the new description for the event type
Return Value
This API returns an UpdateEventTypeInfo hash with the following keys (a description of the new workflow synchronization event type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/sync-events/{type}?action=clone

Description
Clones the current workflow synchronization event type
Arguments
This API takes the following hash arguments:
  • name (*string): the new name for the event type; if not provided, the new name will be generated
  • desc (*string): the new description for the event type
Return Value
This API returns a CloneEventTypeInfo hash with the following keys (a description of the new workflow synchronization event type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/sync-events/{type}?action=events

Description
Returns a hash of information about the current workflow synchronization event type
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: parsed with Qore::parse_boolean(); if True, return in descending order
  • eventkey: the event key value
  • eventname: the event type name
  • limit: max number of rows to return
  • maxmodified: if present, parsed as a date; maximum modified date
  • modified: if present, parsed as a date; minimum modified date
  • offset: row offset
  • posted: the event posted status (True or False)
  • sort: a comma-separated string will be split into a list;columns for sorting the results
Return Value
This API returns a list of REST Workflow Synchronization Event Type Hash elements
See also

GET /api/v8/sync-events/{type}?action=file

Description
Returns the workflow synchronization event type as a file that can be saved

PUT /api/v8/sync-events/{type}?action=post

Description
Posts a workflow synchronization event, allowing all workflow steps blocked on that event to continue processing.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • eventkey: (required) the workflow synchronization event key
Return Value
This API returns a boolean value as follows:
  • True: the event was posted for the first time with this call
  • False: the event was already posted before this call
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: POST-ERROR: missing eventkey argument
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_POST_WORKFLOW_EVENT
See also

/api/v8/sync-events/{type}/{key}

This REST URI path provides actions and information about a particular workflow synchronization event key

GET /api/v8/sync-events/{type}/{key}

Description
Returns a hash of information about the current workflow synchronization event
Return Value
This API returns a REST Workflow Synchronization Event Hash

PUT /api/v8/sync-events/{type}/{key}?action=post

Description
Posts a workflow synchronization event, allowing all workflow steps blocked on that event to continue processing.
Return Value
This API returns a boolean value as follows:
  • True: the event was posted for the first time with this call
  • False: the event was already posted before this call
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_POST_WORKFLOW_EVENT
See also

/api/v8/system

This REST URI path provides actions and information for system functionality

GET /api/v8/system

Description
Returns a hash of system information
Arguments
This API takes no arguments
Return Value
This API returns a QorusSystemInfo hash with the following keys (Current system information):
  • instance-key (string): the system instance key
  • session-id (int): the application session id
  • omq-version (string): the version of the Qorus server
  • omq-build (string): the git hash of the current Qorus build
  • omq-version-code (int): an integer code for the Qorus version as MMmmSS, where MM = the major version, mm = the minor version, SS == the sub version
  • qore-version (string): the version of the underlying qore library used
  • modules (QorusModuleSetInfo): a hash of module info as returned by Qore::get_module_hash(); keys are module names
    • api_major (*int): the API major version for binary modules
    • api_minor (*int): the API minor version for binary modules
    • author (string): the module author's name
    • desc (string): a short description of the module
    • filename (string): the path to the module on the host filesystem
    • info (*UndefinedHash): any additional module-specific information
    • injected (bool): if this module was injected
    • license (*string): the license for the module
    • name (string): the name of the module
    • reexported-modules (*list<string>): list of modules rexported by this module, if any
    • reinjected (bool): if this module was reinjected
    • url (*string): the URL for the module
    • user (*bool): if this is a user module
    • version (string): the version string of the module
  • datamodel-version (string): the version of the datamodel expected by the server
  • omq-schema (string): "user%@dbname" string for the system "omq" datasource
  • omq-driver (string): driver name for the system "omq" datasource
  • omq-db-version (auto): database server version for the system "omq" datasource; the data type depends on the driver
  • omquser-schema (string): "user%@dbname" string for the "omquser" datasource
  • omquser-driver (string): driver name for the "omquser" datasource
  • omquser-db-version (auto): database server version for the "omquser" datasource; the data type depends on the driver
  • starttime (date): date and time the qorus-core server was started
  • hostname (string): hostname where the qorus-core server is running
  • pid (int): PID of the server process
  • threads (int): count of currently active threads in qorus-core
  • schema-properties (QorusSchemaInfo): information about the system schema
    • schema-version (string): the full system schema version
    • schema-compatibility (string): the runtime compatible version
    • schema-load-compatibility (string): the load (oload) compatible version
  • omq_dir (string): the full path on the host to the Qorus application directory
  • cache_size (int): The number of entries in the workflow order data cache
  • shutting_down (bool): indicates if the system is shutting down or not
  • build-type (string): the build type (normally "Production" for public releases)
  • runtime-properties (*UndefinedHash): any runtime properties set on the instance
  • alert-summary (SystemAlertInfo): summary of alerts
    • transient (int): number of current transient alerts
    • ongoing (int): number of ongoing alerts
  • debug (bool): indicates if debugging is enabled for the instance
  • debug-internals (bool): indicates if internal debugging is enabled for the instance
  • health (string): a string indicating the health status of the instance
  • ui-compatibility-version (string): a string indicating the UI compatibility for the instance
  • plugins (*list<string>): any installed plugins
  • system_log_url (string): a WebSocket URL for system log streaming
  • audit_log_url (string): a WebSocket URL for audit log streaming
  • http_log_url (string): a WebSocket URL for HTTP log streaming
  • mon_log_url (string): a WebSocket URL for connection monitor log streaming
  • alert_log_url (string): a WebSocket URL for alert log streaming
  • api_version (string): the current API version
  • cluster_info (QorusClusterSetInfo): cluster info; keys are node (container) names
    • node_priv (int): the memory in use on this node in bytes
    • node_priv_str (string): the memory in use on this node
    • node_ram (int): the total RAM on the host machine in bytes
    • node_ram_str (string): the total RAM on the host machine
    • node_ram_in_use (int): the amount of RAM in use on the host machine in bytes
    • node_ram_in_use_str (string): the amount of RAM in use on the host machine
    • node_cpu_count (int): the number of CPU cores on the host machine
    • node_load_pct (float): the CPU load on the host machine
    • mem_history (list<UndefinedHash>): memory history list
    • process_count (int): number of processes running
    • process_history (list<UndefinedHash>): process history list
  • processes (QorusProcessSetInfo): process info; keys are process IDs
    • client_id (*string): the client ID of the process
    • connstr (*string): the connection string (qdsp processes only)
    • host (string): the hostname where the process is running
    • id (string): the unique process ID in the cluster (same as the hash key)
    • instance_id (string): the unique instance ID for the process
    • java_min_heap (*int): the minimum Java heap size in bytes
    • java_max_heap (*int): the maximum Java heap size in bytes
    • jobid (*int): (job processes only) the job ID
    • jobname (*string): (job processes only) the name of the job
    • jobversion (*string): (job processes only) the version of the job
    • log_pipe (*string): any log pipe for the process
    • node (string): the node name where the process is running
    • pct (*int): the percentage of main memory taken up by the process on the node
    • pid (int): the PID on the host
    • port (*int): any port number for the process
    • priv (*int): the amount of private memory of the process in bytes
    • priv_str (*string): a string description of the priv value
    • prometheus_port (*int): any port number for communicating with Prometheus
    • restarted (*bool): indicates if the process has been restarted
    • rss (*int): the resident size of the process in bytes
    • sessionid (*int): (job processes and workflow processes only) the DB session ID
    • socket_path (*string): any socket path for the process
    • stack_size (*int): the maximum stack size in bytes
    • started (*date): the timestamp the process was started
    • start_code (*int): start code for the process: 0: manual start, 1: manual restart, 2: automatic restart
    • state_label (*string): (service proceses only) the service label ("stateful" for stateful services)
    • status (*int): the process's status code
    • status_string (*string): the process's status as a string
    • svcid (*int): (service proceses only) the service ID
    • svcname (*string): (service proceses only) the service name
    • svctype (*string): (service proceses only) the service type
    • svcversion (*string): (service proceses only) the service version
    • type (*string): the type of the process
    • urls (list<string>): a list of ZeroMQ URLs for the process
    • vsz (*int): the virtual size of the process in bytes
    • wfid (*int): (workflow processes only) the workflow ID
    • wfname (*string): (workflow processes only) the name of the workflow
    • wfversion (*string): (workflow processes only) the version of the workflow
  • workflow_total (int): total number of workflows cached
  • workflow_alerts (int): number of workflows with alerts
  • service_total (int): total number of services cached
  • service_alerts (int): number of services with alerts
  • job_total (int): total number of jobs cached
  • job_alerts (int): number of jobs with alerts
  • remote_total (int): number of remote Qorus connections
  • remote_alerts (int): number of remote Qorus connections with alerts
  • user_total (int): number of user connections
  • user_alerts (int): number of user connections with alerts
  • datasource_total (int): number of datasource connections
  • datasource_alerts (int): number of datasource connections with alerts
  • order_stats (list<UndefinedHash>): list of order status information
  • loggerParams (UndefinedHash): logger param info
  • auth_label_values (list<string>): list of auth label values
  • grafana_panel_ids (*UndefinedHash): hash of grafana panel ID info
  • limits (QorusLimitInfo): Qorus system limit information
    • nofile (int): maximum number of open files
    • nproc (int): maximum number of procesess / threads
  • default_mapper_keys (UndefinedHash): default mapper key info
  • pipeline_options (UndefinedHash): pipeline option info
  • stack_size (int): thread stack size
  • is_kubernetes (bool): if Qorus is runnning in Kubernetes or not
  • edition (string): Enterprise for Qorus Integration Engine(R) Enterprise Edition
  • tz_region (string): the time zone region the server is running in
  • tz_utc_offset (int): the UTC offset in seconds east of UTC; negative numbers indicate west of UTC
  • oauth2_enabled (bool): indicates that the server supports OAuth2
  • templates (list<TemplateInfo>): a list of template info hashes
  • code-server (*CodeServerSet): information about code-server processes; keys are users with active code-server processes
    • pid (int): the PID of the process
    • code_url (string): the URL of the UNIX socket listener
    • proxy_name (string): the name of the Qorus proxy for this process
    • uri_path (string): the URI path for Qorus for the proxy

PUT /api/v8/system?action=autoVarContext

Description
Returns automatic variable information for the given context
Arguments
This API takes the following hash arguments:
  • type (string): the auto variable context (accepted values: event, transaction-block)
  • provider (DataProviderSpecificationInfo): info that specifies a particular data provider
    • type (string): one of connection, datasource, factory or remote
    • name (string): the name of the type, connection, factory, etc
    • path (*string): the path to the final object
    • options (*hash<auto>): create option for type = factory
Return Value
This API returns an AutoVarSet hash with the following keys (a hash giving the current auto variable context; each hash key is a variable name, and each hash value is a hash with the following keys:):
  • type (string): the variable type
  • desc (string): a description for the variable
  • value (auto): the information about variable's value, this will be a data provider hash, for example, if the variable is a data provider
  • variableType (string): the type of variable (ex: "autovar": automatic variable)
  • readOnly (bool): if the variable is read only or not
Errors
  • 400 Bad Request: invalid type or data provider option

GET /api/v8/system?action=defaultLogger

Description
Returns system default logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type.

PUT /api/v8/system?action=defaultLogger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/system?action=defaultLogger

Description
Create system Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/system?action=defaultLogger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system?action=defaultLoggerAppenders

Description
Return system logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

POST /api/v8/system?action=defaultLoggerAppenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/system?action=defaultLoggerAppenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system?action=defaultLoggerAppenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system?action=echo

Description
Echos the argument(s) passed
Arguments
Accepts any arguments
Return Value
Returns all arguments as the response body

PUT /api/v8/system?action=echo

Description
Echos the argument(s) passed
Arguments
This API accepts any arguments
Return Value
This API returns a value of type auto: all arguments are returned in the response body

POST /api/v8/system?action=evalExpression

Description
Evaluates the expression and returns the result
Arguments
This API takes the following hash argument:
  • exp (UndefinedHash): the expression to evaluate
Return Value
This API returns a value of type auto: the result of executing the expression
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/system?action=expressions

Description
Returns information about expressions available in the given context
Arguments
This API takes the following hash arguments:
  • return_type (*string): the return type of the expressions
  • first_arg_type (*string): the argument type of the first argument of the operator or function
  • type (*string): "operator" or "function"; if not present, then all expression types are returned
Return Value
This API returns a value of type list<UndefinedHash>: A list of expressions supported for the context

PUT /api/v8/system?action=getContextData

Description
Returns context data for the given input context or for a generic context if no interface_context is provided
Arguments
This API takes the following hash arguments:
  • interface_context (*string): the context for the data; one of: workflow, service, or job
  • data_context (*string): the data type for any target field; if present, only compatible fields will be returned
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): hash of state data keyed by state name

GET /api/v8/system?action=interfaces

Description
Returns information about interfaces
Arguments
This API takes the following hash arguments:
  • type (*string): the type of interface
  • substring (*string): a substring to match interfaces' label and short_desc values (case-insensitive)
Return Value
This API returns a value of type list<UndefinedHash>: a list of interface and draft information

GET /api/v8/system?action=interfacesWithDataContext

Description
Returns a list of interfaces with a defined data context
Return Value
This API returns a list of hashes with the following keys:
  • iface_kind: the type of interface (workflow, service, or job)
  • name: the name of the interface
  • version: the version of the interface
  • id: the ID of the interface
  • label: a string in the format: name:version

POST /api/v8/system?action=objects

Description
Create or replace integration objects in Qorus
Arguments
This API takes the following hash arguments:
  • classes (*list<UndefinedHash>): the class data to use to create one of more classes
  • constants (*list<UndefinedHash>): the constant data to use to create one of more constants
  • errors (*list<UndefinedHash>): the error set data to create
  • events (*list<UndefinedHash>): the event data to use to create one or more workflow synchronization event types
  • fsms (*list<UndefinedHash>): the FSM data to use to create one or more FSMs
  • functions (*list<UndefinedHash>): the function data to create
  • groups (*list<UndefinedHash>): the group data to create
  • jobs (*list<UndefinedHash>): the job data to create
  • mappers (*list<UndefinedHash>): the mapper data to create
  • pipelines (*list<UndefinedHash>): the pipeline data to use to create one or more pipelines
  • queues (*list<UndefinedHash>): the queue data to use to create one or more queues
  • services (*list<UndefinedHash>): the service data to create
  • steps (*list<UndefinedHash>): the step data to create
  • workflows (*list<UndefinedHash>): the workflow data to create
  • vmaps (*list<UndefinedHash>): the value map data to create
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): the result of the action
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/system?action=ping

Description
Returns "OK"
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"

POST /api/v8/system?action=refreshSnapshots

Description
Refresh database snapshots for job and workflow instances
Arguments
This API takes no arguments
Return Value
This API returns an UndefinedHash hash; keys have the following format:
  • any (auto): a hash giving a result of the operation keyed by snapshot name where values are strings giving the result of the operation
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/system?action=reloadRbac

Description
Reloads the all Role Based Access Control information (users, permissions, roles, groups) from the system schema
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

PUT /api/v8/system?action=restart

Description
Shuts down and restarts the system; this call starts the process and returns immediately
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • timeout: (optional) a timeout in seconds; the currently running system will be killed if it does not shut down within this time period; if not given, the default timeout is 2 minutes (120 seconds)
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SHUTDOWN
See also

PUT /api/v8/system?action=rotateLogFiles

Description
Rotates all system log files. The number of old log files kept is controlled by system option qorus.max-log-files . It is recommended to use the qorus-log-rotator service to rotate log files instead of calling this API method directly.
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

PUT /api/v8/system?action=setDebug

Description
Turns system debugging on or off; when system debugging is enabled, additional information is logged when exceptions are thrown
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns a hash with the following key:
  • system-debugging: the system debugging setting as a boolean value

PUT /api/v8/system?action=shutdown

Description
This API will start the asynchronous shutdown process in the Qorus system. The response indicates only that the shutdown process has begun, and not that the system has been fully shut down. Check the log file or the process list to verify that the system has completely stopped.
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SHUTDOWN-ALREADY-IN-PROGRESS: system shutdown is already in progress
Note
Requires one of the following permissions:

PUT /api/v8/system?action=shutdownWait

Description
Shuts down the system and returns when the system shutdown process is complete
Arguments
This API takes no arguments
Return Value
This API returns a value of type string: "OK"
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
Requires one of the following permissions:

PUT /api/v8/system?action=stream

Description
Returns a test stream depending on the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • stream: (optional) the name of the stream to return; can be:
    • "DataStream": returns a short output DataStream of lists of hashes
    • "EchoDataStream": returns an input/output DataStream where the input is immediately returned as output
    • any other value: returns a short test stream of string data
Return Value
Returns a stream depending on the arguments; see above for details

POST /api/v8/system?action=stream

Description
Returns a test stream depending on the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • stream: (optional) the name of the stream to return; can be:
    • "DataStream": returns a short output DataStream of lists of hashes
    • "EchoDataStream": returns an input/output DataStream where the input is immediately returned as output
    • any other value: returns a short test stream of string data
Return Value
Returns a stream depending on the arguments; see above for details

GET /api/v8/system?action=stream

Description
Returns a test stream depending on the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • stream: (optional) the name of the stream to return; can be:
    • "DataStream": returns a short output DataStream of lists of hashes
    • any other value: returns a short test stream of string data
Return Value
Returns a stream depending on the arguments; see above for details

GET /api/v8/system?action=validateWsToken

Description
Returns the username associated with the given token or NOTHING if the token is not valid
Arguments
This API takes the following hash argument:
  • token (string): the token string
Return Value
This API returns a value of type *string: The username corresponding to the token if the token is valid otherwise NOTHING
Errors
  • 400 Bad Request: missing "token" argument or invalid argument type
  • 409 Conflict: TOKEN-ERROR: invalid token

GET /api/v8/system?action=wstoken

Description
Returns a token for the current user for web socket / HTTP / REST communication with the Qorus server. The token can be used in requests in the Qorus-Token header to provide authentication for future requests up to the lifetime of the token. Tokens are valid only for the current session; to use persistent, long-lived tokens, please use OAuth2 authentication instead. The maximum token duration is 2 days; longer durations will be capped to 2 days.
Arguments
This API takes the following hash argument:
  • ttl (*int): duration of validity of the token in seconds; if not present, defaults to 10 minutes
Return Value
This API returns a value of type string: The string token to be used for HTTP or websocket communication in the Qorus-Token header

/api/v8/system/alert/logger

This URI path provides ability to customize the Qorus alert logger

DELETE /api/v8/system/alert/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/alert/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/alert/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/alert/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/alerts

This REST URI path provides actions and information related to system alerts

GET /api/v8/system/alerts

Description
Returns a list of hashes of information about system alerts
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • remote: (optional) the name of a remote Qorus connection to retrieve alerts for and add to the return value
  • summary: (optional) parsed with Qore::parse_boolean(); if True the return value is a hash with the following keys:
    • "cutoff": the transient cut off date used
    • "transient": the count of transient alerts
    • "ongoing": the count of ongoing alerts
  • cutoff: (optional) parsed as a date; the cutoff date/time for transient alerts (only used when summary is True); transient events after this point in time are not considered in the summarized result
Return Value
This API returns a list of REST Alert Hash elements for system alerts unless the summary option is passed (see above for details)

/api/v8/system/alerts/ongoing

This REST URI path provides actions and information related to ongoing system alerts

GET /api/v8/system/alerts/ongoing

Description
Returns a list of hashes of information about ongoing system alerts
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • remote: (optional) the name of a remote Qorus connection to retrieve ongoing alerts for and add to the return value
Return Value
This API returns a list of REST Alert Hash elements for ongoing system alerts

/api/v8/system/alerts/transient

This REST URI path provides actions and information related to transient system alerts

GET /api/v8/system/alerts/transient

Description
Returns a list of hashes of information about transient system alerts
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • remote: (optional) the name of a remote Qorus connection to retrieve transient alerts for and add to the return value
  • max: (optional) the maximum number of local alerts to return; defaults to 50 if not given
Return Value
This API returns a list of REST Alert Hash elements for transient system alerts

/api/v8/system/api

This REST URI path provides actions and information about the system RPC API

PUT /api/v8/system/api?action=call

Description
Calls a system RPC API method and returns the return value
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • method: (required) the string method name to call; if no "." characters are found in the method name, then it is prefixed with "omq.system."; if the method starts with "system." or "user.", then "omq." is prefixed to the method; if the method starts with "group." or "job.", then "omq.system." is prefixed to the method name
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the method arguments; parse_args takes precedence over args
  • [args]: any arguments passed here will be used directly as the method arguments
Return Value
This API returns result of calling the given RPC API method with the given arguments
Errors
  • 409 Conflict: API-ERROR: missing or invalid "method" key
See also
the RPC API method in question for information about arguments, return types, or permissions required

/api/v8/system/audit/logger

This URI path provides ability to customize the Qorus audit logger

DELETE /api/v8/system/audit/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/audit/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/audit/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/audit/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/authlabels

This REST URI path provides information about authentication labels

GET /api/v8/system/authlabels

Description
Returns a hash of authentication labels existing in Qorus
Return Value
This API returns a hash with the following keys:
  • authlabelid: (string) key for the hash value assigned a value of a list of hashes with the following keys:
    • authlabelid: (string) unique identifier of the label
    • serviceid: (int) the service ID again
    • value: (string) the value of the authentication label
    • servicename: (string) the name of the service

/api/v8/system/config

This REST URI path provides actions and information related to Qorus configuration item values on the global level

DELETE /api/v8/system/config

Description
Deletes values of the given config items.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • config-items: list of hashes describing config item values, each hash has the following keys:
    • name: name of the config item
    • prefix: prefix of the config item (optional)
    • level: level of the config item value
Return Value
This API returns a hash with the following keys:
  • results: list of hashes, where each hash has the following keys:
    • deleted: True in case value has been deleted otherwise False
    • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 400 Bad Request: returned if the request has no config-items key
Note

GET /api/v8/system/config

Description
Returns a list of all configuration item values on the global level
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "is_templated_string": True if the value is a templated string that can be later expanded

POST /api/v8/system/config

Description
Creates the value for the given configuration items
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: the name of the configuration item
  • prefix: the prefix of the configuration item (optional)
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the workflow configuration item change action
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: QR_SERVER_CONTROL: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 400 Bad Request: returned if the request has no value or name keys
Note

PUT /api/v8/system/config

Description
Imports the given config item values.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • config-items: list of hashes describing config item values, each hash has the following keys:
    • name: name of the config item
    • prefix: prefix of the config item (optional)
    • interface-type: interface type (job, service, step, workflow, global)
    • interface-name: name of the interface (required if interface type is not global)
    • interface-version: version of the interface (required if interface type is not global)
    • value: value of the config item
Return Value
This API returns a hash with the following keys:
  • results: list of hashes, where each hash has the following keys:
    • updated: True or False (in case value was set before)
    • inserted: True or False (in case value was not set before)
    • value: new value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 400 Bad Request: returned if the request has no config-items key
Note

POST /api/v8/system/config?action=yaml

Description
Sets the value for the given configuration items using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: the name of the configuration item
  • prefix: the prefix of the configuration item (optional)
  • value: (YAML-serialized string) the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the workflow configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value or name keys
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/system/config?action=yaml

Description
Imports the given config item values from YAML-serialized strings.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • config-items: list of hashes describing config item values, each hash has the following keys:
    • name: name of the config item
    • prefix: prefix of the config item (optional)
    • interface-type: interface type (job, service, step, workflow, global)
    • interface-name: name of the interface (required if interface type is not global)
    • interface-version: version of the interface (required if interface type is not global)
    • value: value of the config item (YAML-serialized string)
Return Value
This API returns a hash with the following keys:
  • results: list of hashes, where each hash has the following keys:
    • updated: True or False (in case value was set before)
    • inserted: True or False (in case value was not set before)
    • value: new value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 400 Bad Request: returned if the request has no config-items key
Note

GET /api/v8/system/config?action=yaml

Description
Returns a list of all configuration item values on the global level
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/system/config/{name}

This REST URI path provides actions and information related to a specific Qorus global configuration item. Prefix can be passed within the config item name or as following: /v3/system/config/{name}?prefix={prefix}.

DELETE /api/v8/system/config/{name}

Description
Permanently deletes the current value for the configuration item on the global level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/system/config/{name}

Description
Returns a hash for the current configuration item value on the global level
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "is_templated_string": True if the value is a templated string that can be later expanded

PUT /api/v8/system/config/{name}

Description
Sets the value for the given configuration item on the global level
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value (required): the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: CONFIG-ITEM-ERROR: this exception is thrown if an invalid type is given for the given configuration item
Note

PUT /api/v8/system/config/{name}?action=yaml

Description
Sets the value for the given global configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value (YAML-serialized string): the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/system/config/{name}?action=yaml

Description
Returns a hash for the current configuration item value as a YAML-serialized string on the global level
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "is_templated_string": True if the value is a templated string that can be later expanded

DELETE /api/v8/system/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on the global level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/system/health

This REST URI path provides actions and information about system health

GET /api/v8/system/health

Description
Returns a hash describing the health of the system and monitored remote systems
Return Value
This API returns a hash with the following keys:
  • transient: the number of transient alerts
  • ongoing: the number of ongoing alerts
  • health: a string color code for the health of the system with the following values:
    • "GREEN": good health
    • "YELLOW": warning
    • "RED": problems
  • instance-key: the instance key for the system
  • remote: a list of health information for remotely-monitored Qorus instances with the same keys as this hash (minus "remote")
Return Value Example
hash: (5 members)
  transient : 0
  ongoing : 123
  health : "RED"
  instance-key : "quark-1"
  remote : <EMPTY LIST>

/api/v8/system/http/logger

This URI path provides ability to customize the Qorus http logger

DELETE /api/v8/system/http/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/http/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/http/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/http/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/listeners

This REST URI path provides actions and information related to Qorus HTTP listeners

GET /api/v8/system/listeners

Description
Returns a hash of hashes of information about HTTP listeners
Arguments
This API takes no arguments
Return Value
This API returns a ListenerInfoSet hash with the following keys (hash of hashes keyed by listener ID providing information about Qorus listeners):
  • name (string): the unique name of the listener
  • hostname (*string): the bind hostname
  • hostname_desc (*string): a description for the hostname
  • address (string): the bind address
  • address_desc (string): a description for the address
  • port (*int): the port number (not present in UNIX sockets)
  • family (int): the network address family code for the socket
  • familystr (string): a descriptive string for the family code
  • ssl (bool): True if the listener is a TLS/SSL listener
  • desc (string): a descriptive string for the listener
  • proto (string): the protocol; either "http" or "https"
  • id (int): the listener ID
  • bind (string): the bind string
  • get_remote_certs (bool): flag if remote client certificates will be captured
  • ssl_verify_flags (list<string>): SSL verification flags (see SSL Verification Mode Constants for the meaning of these values)
  • ssl_accept_all_certs (bool): if the listener will accept all client certificates (verification disabled) or not (verification enabled)

POST /api/v8/system/listeners

Description
Starts one or more listeners on the given bind address
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • bind: the 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_file]: (optional) the file name of the X.509 certificate in PEM format (only for HTTPS listeners)
  • [key_file]: (optional) the file name of the private key for the X.509 certificate in PEM format (only for HTTPS listeners)
  • [key_password]: (optional) the password to the private key, if any
  • [family]: (optional) the integer network address family code or symbolic string name
  • [name]: (optional) the name of the listener; if not provided a unique name will be generated
Return Value
This API returns 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")
Errors
  • 400 Bad Request: if no listeners can be started, then the message body in the response gives
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_START_LISTENER

POST /api/v8/system/listeners?action=start

Description
Starts one or more listeners on the given bind address
See also
This API is equivalent to POST /api/system/listeners; see that documentation for details.

/api/v8/system/listeners/{id_or_name}

This REST URI path provides actions and information related to a specific HTTP listener

DELETE /api/v8/system/listeners/{id_or_name}

Description
Stops the current listener
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: LISTENER-ARG-ERROR: cannot stop a listener via a request handled by the same listener
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/system/listeners/{id_or_name}

Description
Returns a hash of information about the current listener
Arguments
Return Value
This API returns a ListenerInfoHash hash with the following keys (information about the current listener):
  • name (string): the unique name of the listener
  • hostname (*string): the bind hostname
  • hostname_desc (*string): a description for the hostname
  • address (string): the bind address
  • address_desc (string): a description for the address
  • port (*int): the port number (not present in UNIX sockets)
  • family (int): the network address family code for the socket
  • familystr (string): a descriptive string for the family code
  • ssl (bool): True if the listener is a TLS/SSL listener
  • desc (string): a descriptive string for the listener
  • proto (string): the protocol; either "http" or "https"
  • id (int): the listener ID
  • bind (string): the bind string
  • get_remote_certs (bool): flag if remote client certificates will be captured
  • ssl_verify_flags (list<string>): SSL verification flags (see SSL Verification Mode Constants for the meaning of these values)
  • ssl_accept_all_certs (bool): if the listener will accept all client certificates (verification disabled) or not (verification enabled)

GET /api/v8/system/listeners/{id_or_name}?action=logOptions

Description
Returns a code giving the logging options set for the current listener
Return Value
Returns the integer value of Listener Log Options set for the current listener combined by binary or
See also

PUT /api/v8/system/listeners/{id_or_name}?action=logVerboseAll

Description
Turns on and off verbose logging for the current listener; verbose logging means that HTTP headers and bodies are logged (which can produce lots of data in log files)
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • flag: (optional) if present, parsed with Qore::parse_boolean(); if True then verbose logging is enabled for the current listener, if False, then it is disabled; default value if not present True
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
  • requires permission OMQ::QR_SERVER_CONTROL
  • it is recommended to enable verbose logging only as a debug option
Warning
this option can result in sensitive data being logged; use with care
See also

POST /api/v8/system/listeners/{id_or_name}?action=reloadCertificate

Description
Reloads the certificate and private key from the original file locations and uses the new certificate for new connections
Arguments
Return Value
This API returns a value of type string: the string "OK"
Errors
  • 401 Unauthorized: listener is not an HTTPS listener or no certificate source location information is stored against the listener
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/system/listeners/{id_or_name}?action=setLogOptions

Description
Sets logging options for the current listener according to the option argument passed
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "option" argument
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONTROL
Warning
this option can result in sensitive data being logged; use with care
See also

POST /api/v8/system/listeners/{id_or_name}?action=stop

Description
Stops the current listener
Errors
  • 400 Bad Request: LISTENER-ARG-ERROR: cannot stop a listener via a request handled by the same listener
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
See also
This API is equivalent to DELETE /api/system/listeners/{id_or_name}; see that documentation for details.

/api/v8/system/logger/appenders

This URI path provides ability to customize Qorus system logger appenders

DELETE /api/v8/system/logger/appenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/logger/appenders

Description
Return system logger appenders
Arguments
This API takes the following argument as URI arguments:
  • id: (string) id of appender to get
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

POST /api/v8/system/logger/appenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/logger/appenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppender File, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/loggers

Returns all system loggers

GET /api/v8/system/loggers

Description
Returns all system loggers
Return Value
This API returns 200 OK and list with hashes with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services). If set means default logger

/api/v8/system/metadata

This REST URI path provides actions and information related to the system metadata cache.

Since
Qorus 4.0

PUT /api/v8/system/metadata?action=reload

Description
Reloads data in the named metadata caches and resets affected workflows, services, and jobs
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • workflows: a list of workflow IDs to reload in the metadata cache and reset
  • services: a list of service IDs to reload in the metadata cache and to reset
  • jobs: a list of job IDs to reload in the metadata cache and to reset
  • mappers: a list of mapper IDs to reload in the metadata cache
  • vmaps: a list of value map IDs to reload in the metadata cache
  • functions: a list of functions IDs to reload in the metadata cache
  • classes: a list of class IDs to reload in the metadata cache
  • constants: a list of constant IDs to reload in the metadata cache
  • queues: a list of queue IDs to reload in the metadata cache
  • events: a list of event IDs to reload in the metadata cache
  • steps: a list of step IDs to reload in the metadata cache
  • config_values: a list of config item names to reload in the metadata cache
  • types: a list of type paths to reload in the metadata cache
Return Value
This method returns a hash with keys depending on the arguments as follows:
  • workflows: the number of workflows updated in the metadata cache
  • services: the number of services updated in the metadata cache
  • jobs: the number of jobs updated in the metadata cache
  • mappers: the number of mappers updated in the metadata cache
  • vmaps: the number of value maps updated in the metadata cache
  • functions: the number of functions updated in the metadata cache
  • classes: the number of classes updated in the metadata cache
  • constants: the number of constants updated in the metadata cache
  • queues: the number of queues updated in the metadata cache
  • events: the number of events updated in the metadata cache
  • steps: the number of steps updated in the metadata cache
  • config_values: the number of configuration item values updated in the metadata cache
  • workflow_reset: a hash of workflow reset info; see the return value of PUT /api/workflows?action=reset for a description of this hash
  • service_reset: a hash of service reset info; see the return value of PUT /api/services?action=reset for a description of this hash
  • job_reset: a hash of job reset info; see the return value of PUT /api/jobs?action=reset for a description of this hash
  • types: the number of types in the metadata cache
Errors
  • 409 Conflict: METADATA-RELOAD-ERROR: unknown metadata keys passed
Note
requires permissions depending on the arguments:

/api/v8/system/metadata/classid/{name}

REST metadata URI path

GET /api/v8/system/metadata/classid/{name}

Description
Returns the classid from the class name and optional version, throws an exception if no match is found
Return Value
The integer classid value
Errors
  • 409 Conflict: CLASS-ERROR: class does not exist
Note
The latest version of the class is determined by the creation time of the class and not by a logical version string comparison

/api/v8/system/metadata/classid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/classid/{name}/{version}

Description
Looks up the class ID from the name and version
Return Value
The integer classid value
Errors
  • 409 Conflict: CLASS-ERROR: class does not exist

/api/v8/system/metadata/classmap

REST metadata URI path

GET /api/v8/system/metadata/classmap

Description
Returns a map of class ids to constant info

/api/v8/system/metadata/classrmap

REST metadata URI path

GET /api/v8/system/metadata/classrmap

Description
Returns a map of class names to class ids

/api/v8/system/metadata/constantid/{name}

REST metadata URI path

GET /api/v8/system/metadata/constantid/{name}

Description
Looks up the latest constant id(s) from the name
Return Value
The integer constant ID value
Errors
  • 409 Conflict: CONSTANT-ERROR: constant does not exist
Note
The latest version of the constant is determined by the creation time of the constant and not by a logical version string comparison

/api/v8/system/metadata/constantid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/constantid/{name}/{version}

Description
Looks up the constant ID from the name and version
Return Value
The integer constantid value
Errors
  • 409 Conflict: CONSTANT-ERROR: constant does not exist

/api/v8/system/metadata/constmap

REST metadata URI path

GET /api/v8/system/metadata/constmap

Description
Returns a map of constant ids to constant info

/api/v8/system/metadata/constrmap

REST metadata URI path

GET /api/v8/system/metadata/constrmap

Description
Returns a map of constant names to constant ids

/api/v8/system/metadata/emap

REST metadata URI path

GET /api/v8/system/metadata/emap

Description
Returns a map of workflow synchronization event ids to workflow synchronization event info

/api/v8/system/metadata/ermap

REST metadata URI path

GET /api/v8/system/metadata/ermap

Description
Returns a map of workflow synchronization event type names to workflow synchronization event ids

/api/v8/system/metadata/functionid/{name}

REST metadata URI path

GET /api/v8/system/metadata/functionid/{name}

Description
Looks up the function ID from the name
Return Value
Returns the functionid for the given function name
Errors
  • 409 Conflict: FUNCTION-ERROR: function cannot be found

/api/v8/system/metadata/functionid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/functionid/{name}/{version}

Description
Returns the functionid from the function name and version, throws an exception if no match is found
Return Value
Returns the functionid for the given function name and version
Errors
  • 409 Conflict: FUNCTION-ERROR: function cannot be found

/api/v8/system/metadata/functionmap

GET /api/v8/system/metadata/functionmap

Description
Returns a map of function instance ids to function info

/api/v8/system/metadata/functionrmap

GET /api/v8/system/metadata/functionrmap

Description
Returns a map of function names to function instance ids

/api/v8/system/metadata/getConfigItemValues

REST metadata URI path

GET /api/v8/system/metadata/getConfigItemValues

Description
Return configuration item value information

/api/v8/system/metadata/getworkflowlist

REST metadata URI path

GET /api/v8/system/metadata/getworkflowlist

Description
Returns a list of cached workflow information enhanced with step and function information from the cache
Arguments
This API takes the following arguments:
  • with_deprecated (bool): include deprecated workflows in return list (default: do not include)
Note
This method is subject to RBAC access filtering

/api/v8/system/metadata/jmap

REST metadata URI path

GET /api/v8/system/metadata/jmap

Description
Returns a map of job ids to job info

/api/v8/system/metadata/jobid/{name}

REST metadata URI path

GET /api/v8/system/metadata/jobid/{name}

Description
Returns the job ID from the job name, throws an exception if no match is found
Return Value
The integer job ID value
Errors
  • 409 Conflict: JOB-ERROR: job does not exist
Note
The latest version of the job is determined by the creation time of the job and not by a logical version string comparison

/api/v8/system/metadata/jobid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/jobid/{name}/{version}

Description
Looks up the job ID from the name and version
Return Value
The integer jobid value
Errors
  • 409 Conflict: JOB-ERROR: job does not exist

/api/v8/system/metadata/jobids

REST metadata URI path

GET /api/v8/system/metadata/jobids

Description
Returns a list of all job ids

/api/v8/system/metadata/joblist

REST metadata URI path

GET /api/v8/system/metadata/joblist

Description
Returns a list of integers of known job ids

/api/v8/system/metadata/jobname/{jobid}

REST metadata URI path

GET /api/v8/system/metadata/jobname/{jobid}

Description
Looks up the job name from the jobid, throws an exception if the ID is not recognized
Return Value
The name of the job
Errors
  • 409 Conflict: JOB-ERROR: job does not exist

/api/v8/system/metadata/jrmap

REST metadata URI path

GET /api/v8/system/metadata/jrmap

Description
Returns a map of job names to job ids

/api/v8/system/metadata/lookupclass/{cid}

REST metadata URI path

GET /api/v8/system/metadata/lookupclass/{cid}

Description
Looks up class information from the classid
Return Value
NOTHING if the classid does not match any cached class, otherwise a hash with the following keys:
  • name: the name of the class
  • version: the version of the class
  • patch: the patch string for the class
  • description: the description of the class
  • created: the date/time the class was created
  • modified: the date/time the class was last modified

/api/v8/system/metadata/lookupconstant/{cid}

REST metadata URI path

GET /api/v8/system/metadata/lookupconstant/{cid}

Description
Looks up constant information from the constantid
Return Value
NOTHING if the constantid does not match any cached constant, otherwise a hash with the following keys:
  • name: the name of the constant
  • version: the version of the constant
  • patch: the patch string for the constant
  • description: the description of the constant
  • created: the date/time the constant was created
  • modified: the date/time the constant was last modified

/api/v8/system/metadata/lookupevent/{eid}

REST metadata URI path

GET /api/v8/system/metadata/lookupevent/{eid}

Description
Looks up event information from the workflow_event_typeid
Return Value
NOTHING if the id does not match any cached event, otherwise a hash with the following keys:
  • name: the name of the event
  • desc: the description of the event

/api/v8/system/metadata/lookupfunc/{funcid}

REST metadata URI path

GET /api/v8/system/metadata/lookupfunc/{funcid}

Description
Looks up function info from the function ID
Return Value
Returns a hash with function metadata
Errors
  • 409 Conflict: OMQMAP-LOOKUPFUNC-ERROR: this error will be thrown if the function ID passed is not a valid function ID

/api/v8/system/metadata/lookupjob/{jid}

REST metadata URI path

GET /api/v8/system/metadata/lookupjob/{jid}

Description
Looks up job information from the jobid
Return Value
NOTHING if the jobid does not match any cached job, otherwise a hash with the following keys:
  • jobid: the job id (always same as the argument)
  • name: the name of the job
  • version: the version of the job
  • description: the description of the job
  • active: a boolean flag indicating if the job is active or not; active jobs will be running unless they are a member of a disabled group
  • created: the date/time the job was created
  • modified: the date/time the job was last modified

/api/v8/system/metadata/lookupmapper/{mid}

REST metadata URI path

GET /api/v8/system/metadata/lookupmapper/{mid}

Description
Looks up mapper information from the mapperid
Return Value
NOTHING if the mapperid does not match any cached mapper, otherwise a hash with the following keys:
  • name: the name of the mapper
  • version: the version of the mapper
  • patch: the patch string for the mapper
  • description: the description of the mapper
  • author: the author of the mapper
  • type: the type or class of the mapper
  • fields: the source of the mapper field description hash
  • options: the mapper's option hash
  • created: the date/time the mapper was created
  • modified: the date/time the mapper was last modified

/api/v8/system/metadata/lookupqueue/{qid}

REST metadata URI path

GET /api/v8/system/metadata/lookupqueue/{qid}

Description
Looks up queue information from the queueid
Return Value
NOTHING if the given ID is not a valid queue ID or a hash of queue information with the following keys:
  • name: the name of the queue
  • serviceid: the service associated with the queue
Note
Currently the service association is ignored by Qorus and is provided for informational purposes only

/api/v8/system/metadata/lookupservice/{serviceid}

REST metadata URI path

GET /api/v8/system/metadata/lookupservice/{serviceid}

Description
Looks up service information from the serviceid
Return Value
NOTHING if the serviceid does not correspond to a cached service, otherwise a hash with the following keys:
  • type: either "system" or "user"
  • name: the name of the service
  • version: the version of the service
  • patch: the patch string for the service
  • description: the description of the service
  • created: the creation date/time of the service
  • modified: the date/time the service was last modified
  • autostart: boolean value for autostart status
  • manual_autostart: boolean value for the manual_autostart flag

/api/v8/system/metadata/lookupserviceinfo/{type}/{name}

REST metadata URI path

GET /api/v8/system/metadata/lookupserviceinfo/{type}/{name}

Description
Looks up service information from the type and name
Return Value
NOTHING if the service does not correspond to a cached service, otherwise a hash with the following keys:
  • type: either "system" or "user"
  • name: the name of the service
  • version: the version of the service
  • patch: the patch string for the service
  • description: the description of the service
  • created: the creation date/time of the service
  • modified: the date/time the service was last modified
  • autostart: boolean value for autostart status
  • manual_autostart: boolean value for the manual_autostart flag

/api/v8/system/metadata/lookupsla/{slaid}

REST metadata URI path

GET /api/v8/system/metadata/lookupsla/{slaid}

Description
Looks up SLA information from the slaid
Return Value
NOTHING if the given ID is not a valid SLA ID or a hash of SLA information with the following keys:
  • name: the name of the SLA
  • type: the type of the SLA
  • description: the description of the SLA

/api/v8/system/metadata/lookupstep/{stepid}

REST metadata URI path

GET /api/v8/system/metadata/lookupstep/{stepid}

Description
Returns a hash of info for the given stepid or no value if the step id does not exist
Arguments
This API takes the following argument:
  • verbose: if True then more information is returned
Return Value
A hash of step info for the given stepid or no value if the stepid does not exist

/api/v8/system/metadata/lookupsteps

REST metadata URI path

GET /api/v8/system/metadata/lookupsteps

Description
Returns a hash keyed by stepid of info for the given stepid(s) or no value if the step ids do not exist
Arguments
This API takes the following arguments:
  • ids: one or more stepids to lookup
  • verbose: if True then more information is returned
Return Value
A hash keyed by stepid with values as step info hashes for each valid step; unknown steps are ignored

/api/v8/system/metadata/lookupvmap/{mid}

REST metadata URI path

GET /api/v8/system/metadata/lookupvmap/{mid}

Description
Looks up value map information from the value map id
Return Value
NOTHING if the value map id does not match any cached value map, otherwise a hash with the following keys:
  • name: the name of the value map
  • version: the version of the value map
  • patch: the patch string for the value map
  • description: the description of the value map
  • author: the author of the value map
  • type: the type or class of the value map
  • created: the date/time the value map was created
  • modified: the date/time the value map was last modified

/api/v8/system/metadata/lookupworkflow/{wfid}

REST metadata URI path

GET /api/v8/system/metadata/lookupworkflow/{wfid}

Description
Looks up workflow information from the workflowid
Arguments
This API takes the following arguments:
  • verbose: if True then additional step and function information is included in the return value
Return Value
NOTHING if the workflowid does not match any cached workflow, otherwise a workflow information hash

/api/v8/system/metadata/mapperid/{name}

REST metadata URI path

GET /api/v8/system/metadata/mapperid/{name}

Description
Looks up the latest mapper ID from the name
Return Value
The mapperid from the mapper name and version
Errors
  • 409 Conflict: MAPPER-ERROR: mapper does not exist
Note
The latest version of the mapper is determined by the creation time of the mapper and not by a logical version string comparison

/api/v8/system/metadata/mapperid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/mapperid/{name}/{version}

Description
Looks up the mapper ID from the name and version
Return Value
The mapperid from the mapper name and version
Errors
  • 409 Conflict: MAPPER-ERROR: mapper does not exist

/api/v8/system/metadata/mmap

REST metadata URI path

GET /api/v8/system/metadata/mmap

Description
Returns a map of mapper ids to mapper info

/api/v8/system/metadata/mrmap

REST metadata URI path

GET /api/v8/system/metadata/mrmap

Description
Returns a map of mapper names and versions to mapper IDs

/api/v8/system/metadata/pgmlist

REST metadata URI path

GET /api/v8/system/metadata/pgmlist

Description
Returns a list of debuggable interfaces (type, interface name, version, pgm_name, remote process)

/api/v8/system/metadata/pmap

REST metadata URI path

GET /api/v8/system/metadata/pmap

Description
Return a list of process hashes

/api/v8/system/metadata/qmap

REST metadata URI path

GET /api/v8/system/metadata/qmap

Description
Returns a map of queue ids to queue info

/api/v8/system/metadata/qrmap

REST metadata URI path

GET /api/v8/system/metadata/qrmap

Description
Returns a map of queue names to queue ids

/api/v8/system/metadata/reload

See also PUT /api/v3/system/metadata?action=reload

PUT /api/v8/system/metadata?action=reload

Description
Reloads the given metadata cache and resets affected interface objects according to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); all keys are optional:
  • workflows: a list of workflow IDs to reload in the metadata cache and reset
  • services: a list of service IDs to reload in the metadata cache and to reset
  • jobs: a list of job IDs to reload in the metadata cache and to reset
  • mappers: a list of mapper IDs to reload in the metadata cache
  • vmaps: a list of value map IDs to reload in the metadata cache
  • functions: a list of functions IDs to reload in the metadata cache
  • classes: a list of class IDs to reload in the metadata cache
  • constants: a list of constant IDs to reload in the metadata cache
  • queues: a list of queue IDs to reload in the metadata cache
  • events: a list of event IDs to reload in the metadata cache
  • steps: a list of step IDs to reload in the metadata cache
  • config_values: a list of config item names to reload their values in the metadata cache
Return Value
This method returns a hash with keys depending on the arguments as follows:
  • workflows: the number of workflows updated in the metadata cache
  • services: the number of services updated in the metadata cache
  • jobs: the number of jobs updated in the metadata cache
  • mappers: the number of mappers updated in the metadata cache
  • vmaps: the number of value maps updated in the metadata cache
  • functions: the number of functions updated in the metadata cache
  • classes: the number of classes updated in the metadata cache
  • constants: the number of constants updated in the metadata cache
  • queues: the number of queues updated in the metadata cache
  • events: the number of events updated in the metadata cache
  • steps: the number of steps updated in the metadata cache
  • config_values: the number of configuration item values updated in the metadata cache
  • workflow_reset: a hash of workflow reset info; see the return value of PUT /api/workflows?action=reset for a description of this hash
  • service_reset: a hash of service reset info; see the return value of PUT /api/services?action=reset for a description of this hash
  • job_reset: a hash of job reset info; see the return value of PUT /api/jobs?action=reset for a description of this hash
Errors
  • 409 Conflict: METADATA-RELOAD-ERROR: unknown metadata keys passed
Note
requires permissions depending on the arguments:

/api/v8/system/metadata/reload/{object_type}

object_type can be one of following PUT calls:

  • all: reload all maps
  • functions
  • classes
  • constants
  • queues
  • events
  • mappers
  • vmaps
  • steps
  • workflows
  • services
  • jobs
  • slas
  • config_values
  • pipelines
  • fsm

PUT /api/v8/system/metadata/reload/{object_type}

Description
Reloads the given metadata cache

/api/v8/system/metadata/rlookupconstant/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupconstant/{name}

Description
Looks up all versions of a constant from the constant's name
Return Value
NOTHING if the arguments do not match a cached constant or a hash where the keys are version strings and the values are the corresponding constant IDs
Note
the latest version of the constant is determined by the creation time of the constant and not by a logical version string comparison

/api/v8/system/metadata/rlookupconstant/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupconstant/{name}/{version}

Description
Looks up the constantid of a particular constant from the name and version
Return Value
NOTHING if the arguments do not match or the constantid for the latest version of the constant
Note
The latest version of the constant is determined by the creation time of the constant and not by a logical version string comparison

/api/v8/system/metadata/rlookupevent/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupevent/{name}

Description
Looks up the event id(s) from the name, optional version (without version returns all versions)
Return Value
NOTHING if the event name does not match any cached event, otherwise a hash with the following keys:
  • workflow_event_typeid: the id of the event
  • desc: the description of the event

/api/v8/system/metadata/rlookupfunc/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupfunc/{name}

Description
Looks up all versions of a function from the function's name
Return Value
Returns NOTHING if the arguments do not match a cached function or a hash where the keys are version strings and the values are the corresponding function IDs
Note
The latest version of the function is determined by the creation time of the function and not by a logical version string comparison

/api/v8/system/metadata/rlookupfunc/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupfunc/{name}/{version}

Description
Looks up the functionid of a particular function from the name and version
Return Value
Returns NOTHING if the arguments do not match or the functionid for the latest version of the function
Note
The latest version of the function is determined by the creation time of the function and not by a logical version string comparison

/api/v8/system/metadata/rlookupjob/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupjob/{name}

Description
Looks up the job information from the name
Return Value
NOTHING if the arguments do not match a cached job or a hash of job information with the following keys:
  • jobid: the job id
  • name: the name of the job (always same as the argument)
  • version: the version of the job
  • description: the description of the job
  • active: a boolean flag indicating if the job is active or not; active jobs will be running unless they are a member of a disabled group
  • created: the date/time the job was created
  • modified: the date/time the job was last modified

/api/v8/system/metadata/rlookupmapper/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupmapper/{name}

Description
Looks up all versions of a mapper from the mapper name
Return Value
NOTHING if the arguments do not match a cached mapper or a hash where the keys are version strings and the values are the corresponding mapper IDs

/api/v8/system/metadata/rlookupmapper/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupmapper/{name}/{version}

Description
Looks up the mapperid of a particular mapper from the name and version
Return Value
NOTHING if the arguments do not match or the mapperid for the requested version of the mapper

/api/v8/system/metadata/rlookupqueue/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupqueue/{name}

Description
Looks up queue information from the queue name
Return Value
NOTHING if the given name is not a valid queue name or a hash of queue information with the following keys:
  • queueid: the queueid of the queue
  • serviceid: the service associated with the queue
Note
Currently the service association is ignored by Qorus and is provided for informational purposes only

/api/v8/system/metadata/rlookupservice/{type}/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupservice/{type}/{name}

Description
Looks up all versions of a service
Return Value
NOTHING if the arguments do not match a cached service or a hash where the keys are version strings and the values are the corresponding service IDs
Note
The latest version of the service is determined by the creation time of the service and not by a logical version string comparison

/api/v8/system/metadata/rlookupservice/{type}/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupservice/{type}/{name}/{version}

Description
Looks up the serviceid from the type, name, and version
Return Value
NOTHING if the arguments do not match or the serviceid for the latest version of the service

/api/v8/system/metadata/rlookupsla/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupsla/{name}

Description
Looks up SLA information from the SLA name
Return Value
NOTHING if the given name is not a valid SLA name or a hash of SLA information with the following keys:
  • slaid: the ID of the SLA
  • type: the type of the SLA
  • description: the description of the SLA

/api/v8/system/metadata/rlookupstep/{stepname}

REST metadata URI path

GET /api/v8/system/metadata/rlookupstep/{stepname}

Description
Returns a hash giving the result of a reverse lookup of step info from its name
Arguments
This API takes the following arguments:
  • name: the name of the step
Return Value
NOTHING if the arguments do not match a cached step or a hash where the keys are version strings and the values are the corresponding step IDs
Note
the latest version of the step is determined by the creation time of the step and not by a logical version string comparison

/api/v8/system/metadata/rlookupstep/{stepname}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupstep/{stepname}/{version}

Description
Looks up the stepid of a particular step from the name and version
Return Value
Returns the stepid for the given version of a step or NOTHING if there is no match

/api/v8/system/metadata/rlookupvmap/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupvmap/{name}

Description
Looks up all versions of a value map from the value map name
Return Value
NOTHING if the arguments do not match a cached value map or a hash where the keys are version strings and the values are the corresponding value map IDs

/api/v8/system/metadata/rlookupworkflow/{name}

REST metadata URI path

GET /api/v8/system/metadata/rlookupworkflow/{name}

Description
Looks up all versions of a workflow from the workflow name
Return Value
NOTHING if the argument does not match a cached workflow or a hash, otherwise the top-level keys of the hash are the cached versions of the workflow and the values are workflow information hashes
Note
Lhe latest version of the workflow is determined by the creation time of the workflow and not by a logical version string comparison

/api/v8/system/metadata/rlookupworkflow/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/rlookupworkflow/{name}/{version}

Description
Returns workflow info from the workflow name and version
Return Value
NOTHING if the arguments do not match a cached workflow or a hash, otherwise a workflow information hash is returned

/api/v8/system/metadata/serviceamap

REST metadata URI path

GET /api/v8/system/metadata/serviceamap

Description
Returns a map of service types (lower case) -> names -> hash (serviceid, version)

/api/v8/system/metadata/serviceid/{type}/{name}

REST metadata URI path

GET /api/v8/system/metadata/serviceid/{type}/{name}

Description
Looks up the last service id(s) from the type, name, optional version
Return Value
The integer serviceid of the latest version of the given service
Note
The latest version of the service is determined by the creation time of the service and not by a logical version string comparison
Errors
  • 409 Conflict: SERVICE-ERROR: service does not exist

/api/v8/system/metadata/serviceid/{type}/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/serviceid/{type}/{name}/{version}

Description
Looks up the last service id(s) from the type, name, optional version
Return Value
The integer serviceid value
Errors
  • 409 Conflict: SERVICE-ERROR: service does not exist

/api/v8/system/metadata/servicelist

REST metadata URI path

GET /api/v8/system/metadata/servicelist

Description
Returns a list of integers of known service ids

/api/v8/system/metadata/servicemap

REST metadata URI path

GET /api/v8/system/metadata/servicemap

Description
Returns a map of service ids to service info

/api/v8/system/metadata/servicermap

REST metadata URI path

GET /api/v8/system/metadata/servicermap

Description
Returns a map of service names to service ids

/api/v8/system/metadata/sla

REST metadata URI path

GET /api/v8/system/metadata/sla

Description
Returns a map of SLA ids to SLA info

/api/v8/system/metadata/slarmap

REST metadata URI path

GET /api/v8/system/metadata/slarmap

Description
Returns a map of SLA names to SLA ids

/api/v8/system/metadata/stepid/{name}

REST metadata URI path

GET /api/v8/system/metadata/stepid/{name}

Description
Returns the stepid from the step name, throws an exception if no match is found
Return Value
Returns the stepid for the given step name
Errors
  • 409 Conflict: STEP-ERROR: step cannot be found

/api/v8/system/metadata/stepid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/stepid/{name}/{version}

Description
Returns the stepid from the step name and version, throws an exception if no match is found
Return Value
Returns the stepid for the given step name and version
Errors
  • 409 Conflict: STEP-ERROR: step cannot be found

/api/v8/system/metadata/stepmap

GET /api/v8/system/metadata/stepmap

Description
Returns a map of stepids to step info

/api/v8/system/metadata/steprmap

GET /api/v8/system/metadata/steprmap

Description
Returns a map of names to step info

/api/v8/system/metadata/svcids

REST metadata URI path

GET /api/v8/system/metadata/svcids

Description
Returns a list of all service ids

/api/v8/system/metadata/systemserviceids

REST metadata URI path

GET /api/v8/system/metadata/systemserviceids

Description
Returns a list of all system service ids

/api/v8/system/metadata/userserviceids

REST metadata URI path

GET /api/v8/system/metadata/userserviceids

Description
Returns a list of all user service ids

/api/v8/system/metadata/vmapid/{name}

REST metadata URI path

GET /api/v8/system/metadata/vmapid/{name}

Description
Looks up the latest value map ID from the name
Return Value
The value map ID from the value map name
Errors
  • 409 Conflict: VALUE-MAP-ERROR: value map does not exist
Note
The latest version of the value map is determined by the creation time of the value map and not by a logical version string comparison

/api/v8/system/metadata/vmapid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/vmapid/{name}/{version}

Description
Looks up the value map ID from the name and version
Return Value
The value map ID from the value map name and version
Errors
  • 409 Conflict: VALUE-MAP-ERROR: value map does not exist

/api/v8/system/metadata/vmmap

REST metadata URI path

GET /api/v8/system/metadata/vmmap

Description
Returns a map of value map ids to value map info

/api/v8/system/metadata/vmrmap

REST metadata URI path

GET /api/v8/system/metadata/vmrmap

Description
Returns a map of value map names to value map IDs

/api/v8/system/metadata/wfids

REST metadata URI path

GET /api/v8/system/metadata/wfids

Description
Returns a list of all workflow ids

/api/v8/system/metadata/wfmap

REST metadata URI path

GET /api/v8/system/metadata/wfmap

Description
Returns a map of workflow ids to workflow info

/api/v8/system/metadata/wfrmap

REST metadata URI path

GET /api/v8/system/metadata/wfrmap

Description
Returns a map of workflow names to workflow ids

/api/v8/system/metadata/workflowid/{name}

REST metadata URI path

GET /api/v8/system/metadata/workflowid/{name}

Description
Looks up the latest workflow id from the name
Return Value
The integer workflowid value
Errors
  • 409 Conflict: WORKFLOW-ERROR: workflow does not exist
Note
The latest version of the workflow is determined by the creation time of the workflow and not by a logical version string comparison

/api/v8/system/metadata/workflowid/{name}/{version}

REST metadata URI path

GET /api/v8/system/metadata/workflowid/{name}/{version}

Description
Looks up the workflow id from the name and version
Return Value
The integer workflowid value
Errors
  • 409 Conflict: WORKFLOW-ERROR: workflow does not exist

/api/v8/system/metadata/workflowlist

REST metadata URI path

GET /api/v8/system/metadata/workflowlist

Description
Returns a list of integers of known workflow ids

/api/v8/system/metadata/{lookup}

This REST URI path provides information related to the system metadata maps and lookups.

This set of API calls provides a thread-safe cache for internal Qorus data. The underlying functionality provided by this service has been moved into the Qorus server to avoid race conditions and dependencies with the service infrastructure. Qorus internally and Qorus system services no longer use this service for metadata lookups, but rather use internal functionality directly.

/api/v8/system/monitoring/logger

This URI path provides ability to customize the Qorus monitoring logger

DELETE /api/v8/system/monitoring/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/monitoring/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/monitoring/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/monitoring/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/options

This REST URI path provides actions and information related to system options; see System Options for more information

GET /api/v8/system/options

Description
Returns a list of system options
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • hash: optional (parsed with Qore::parse_boolean()); if True then the return type is a hash keyed by option name instead of a list
Return Value
This API returns a list of hashes if the hash argument is not set; each element in the list is a REST System Option Hash

PUT /api/v8/system/options?action=flush

Description
Flush current server options to the option file on the server's filesystem
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/system/options?action=set

Description
Sets one or more system options to a new value
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 409 Conflict: OPTION-ERROR: one or more options given was invalid or could not be set
Note
  • requires permission OMQ::QR_OPTION_CONTROL
  • when setting multiple options, an error setting one or more options does not block the other options without errors from being set

PUT /api/v8/system/options?action=setOptions

Description
Sets one or more system options to a new value
See also
This API is equivalent to PUT /api/system/options?action=set; see that documentation for details.

/api/v8/system/options/{options}

This REST URI path provides actions and information related to specific system options; see System Options for more information

GET /api/v8/system/options/{options}

Description
Returns a hash describing the option
Return Value
This API returns a REST System Option Hash

PUT /api/v8/system/options/{options}?action=set

Description
Sets the option to a new value
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (required) the new value for the option
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "value" argument
  • 409 Conflict: OPTION-ERROR: there was an error setting the option
Note
requires permission OMQ::QR_OPTION_CONTROL

/api/v8/system/processes

This REST URI path provides actions and information related to system processes

GET /api/v8/system/processes

Description
Returns a hash of information about currently-running Qorus cluster processes
Return Value
This API returns a hash keyed by cluster process name where values are process info hashes.

/api/v8/system/processes/{id}

This REST URI path provides actions and information related to a specific system process

GET /api/v8/system/processes/{id}

Description
Returns a hash of information about a specific Qorus cluster process
Return Value
This API returns a process info hashes for the current process.

POST /api/v8/system/processes/{id}?action=kill

Description
Kills a cluster process
Return Value
This API returns a hash with the following keys:
  • status: "OK", "ERR" if not
  • code: the return code of the kill() command: 0 if successful, non-zero if not
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/system/props

This REST URI path provides actions and information related to a system properties.

GET /api/v8/system/props

Description
Returns system properties according to the arguments passed.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • domain: (optional) a system property domain to retrieve values for
  • key: (optional) a system property key in the given domain; if key is given then domain must also be passed
Return Value
This API returns:
  • a hash of all domains if no domain value is passed
  • a hash of the given domain if the domain value is passed and the domain exists, otherwise NOTHING
  • the vaule of the given property in the given domain if the domain and key values are passed and the property exists

GET /api/v8/system/props?action=export

Description
Exports properties as a YAML string. Attributes in the "qorus_properties" tag are only informational and are not used when importing. The "omq" domain is not exported.
Return Value
This API returns a YAML-encoded string of all system properties in all domains except the "omq" domain.
Example Return Value
{qorus_properties: {domain1: {key1: "value", key2: "value"},
 ^attributes^: {instance: "quark-1", schema-version: "3.1.0",
 schema-compatibility: "3.1.0", schema-load-compatibility: "3.1.0"}}}
See also
PUT /api/system/props?action=import

PUT /api/v8/system/props?action=import

Description
Import properties from a serialized string (such as exported from GET /api/system/props?action=export); if there are set domains in the list, only enumerated domains are imported
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • domains: (optional) a list of domains to import; a comma-separated string will be split into a list
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY
See also
GET /api/system/props?action=export

PUT /api/v8/system/props?action=reload

Description
Reloads all system properties from the database.
Return Value
This API returns the number of domains loaded
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_RELOAD_PROPERTIES

PUT /api/v8/system/props?action=replaceAll

Description
Replaces all system property keys in one atomic operation
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • props: (required) must be a hash keyed by domain assigned to key-value property hashes; any "omq" domain is ignored
Return Value
This API returns the system property hash passed as an argument.
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit) or invalid type assigned to domain key
Note
requires permission OMQ::QR_SERVER_CONTROL or both OMQ::QR_SET_PROPERTY and OMQ::QR_DELETE_PROPERTY to replace all property values

PUT /api/v8/system/props?action=set

Description
Sets or deletes the value of a single system property in a single domain.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • domain: (required) a string giving the system property domain for the key-value pair
  • key: (required) a string giving the property key value in the given domain
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the property value; parse_args takes precedence over args
  • [args]: arguments passed here will be used directly as the system property value
Return Value
This API returns a string action code as follows:
  • "INSERT": the property was created
  • "UPDATE": the property was updated
  • "DELETE": the property was deleted (existing key, no value passed)
  • "IGNORED": if a non-existent key should be deleted
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: SYSTEM-PROPERTY-ERROR: the given key already exists in the given property domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY to set property values, OMQ::QR_DELETE_PROPERTY to delete property values

PUT /api/v8/system/props?action=updateMany

Description
Sets or deletes the values of one or more system property keys in one or more system property domains
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • arg: (required) must be a hash in the format domain.key.value for updating, inserting, or deleting
Return Value
This API returns a hash of "INSERT", "UPDATE", "DELETE" and "IGNORED" keys with integer values corresponding to the number of operations performed (deleting a non-existent key or domain causes a "IGNORED" value to be returned).
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY to set property values, OMQ::QR_DELETE_PROPERTY to delete property values

/api/v8/system/props/{domain}

This REST URI path provides actions and information related to a specific system property domain.

DELETE /api/v8/system/props/{domain}

Description
Deletes the entire system property domain
Return Value
This API returns a hash of "DELETE" (and "IGNORED" keys in case of a race condition with a competing delete operation on the same system property domain) with integer values corresponding to the number of operations performed.
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_DELETE_PROPERTY

GET /api/v8/system/props/{domain}

Description
Returns the value of the system property domain as a hash or of the specific key(s) given
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • key: (optional) one or more property values in the domain to return; if the string is a comma-separated list, it will be interpreted as a list of keys
Return Value
This API returns the value of the system property domain as a hash (optionally filtered by the key argument as above)

POST /api/v8/system/props/{domain}

Description
Creates an entire system property domain from a hash of key-value pairs
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • arg: (required) a hash giving all key-value pairs for the new system property domain
Return Value
This API returns a hash of "INSERT" (and "UPDATE" in case of a race condition with a parallel request writing to the same system property domain) keys with integer values corresponding to the number of operations performed
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: SYSTEM-PROPERTY-ERROR: the given key already exists in the given property domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY

PUT /api/v8/system/props/{domain}?action=set

Description
Sets the value of a single system property or deletes the system property key if no value is passed.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • key: (required) a string giving the property key value in the current domain
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the property value; parse_args takes precedence over args
  • [args]: arguments passed here will be used directly as the system property value
Return Value
This API returns a string action code as follows:
  • "INSERT": the property was created
  • "UPDATE": the property was updated
  • "DELETE": the property was deleted (existing key, no value passed)
  • "IGNORED": if a non-existent key should be deleted
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY to set property values, OMQ::QR_DELETE_PROPERTY to delete property values

PUT /api/v8/system/props/{domain}?action=updateMany

Description
Sets or deletes the values of one or more system property keys in the current system property domain.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • arg: (required) a key-value hash for updating, inserting, or deleting system properties in the current domain
Return Value
This API returns a hash of "INSERT", "UPDATE", "DELETE" and "IGNORED" keys with integer values corresponding to the number of operations performed (deleting a non-existent key or domain causes a "IGNORED" value to be returned).
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY to set property values, OMQ::QR_DELETE_PROPERTY to delete property values

/api/v8/system/props/{domain}/{key}

This REST URI path provides actions and information related to a specific system property key.

DELETE /api/v8/system/props/{domain}/{key}

Description
Deletes the system property key-value pair.
Return Value
This API returns a string action code as follows:
  • "DELETE": the property was deleted
  • "IGNORED": if a non-existent key should be deleted (only possible with this API with a race condition where the property was deleted in another thread during this request)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_DELETE_PROPERTY

GET /api/v8/system/props/{domain}/{key}

Description
Returns the value of the system property
Return Value
This API returns the value of the system property

POST /api/v8/system/props/{domain}/{key}

Description
Creates a system property with the given value.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body; one of the following hash keys must be present):
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the property value; parse_args takes precedence over arg
  • [arg]: the argument passed here will be used directly as the system property value
Return Value
This API returns a string action code as follows:
  • "INSERT": the property was created
  • "UPDATE": the property was updated (only possible with this API with a race condition where the property was created in another thread during this request)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: SYSTEM-PROPERTY-ERROR: the given key already exists in the given property domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY

PUT /api/v8/system/props/{domain}/{key}?action=set

Description
Sets the value of the system property or deletes the system property key if no value is passed.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • [parse_args]: any string here will be parsed with Util::parse_to_qore_value() and used as the property value; parse_args takes precedence over args
  • [args]: arguments passed here will be used directly as the system property value
Return Value
This API returns a string action code as follows:
  • "INSERT": the property was created (only possible with this API with a race condition where the property was deleted in another thread during this request)
  • "UPDATE": the property was updated
  • "DELETE": the property was deleted (existing key, no value passed)
  • "IGNORED": if a non-existent key should be deleted (only possible with this API with a race condition where the property was deleted in another thread during this request)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: UPDATE-ERROR: changes attempted in the "omq" domain
  • 409 Conflict: PROP-ERROR: serialized value exceeds 4000 bytes (column limit)
Note
requires permission OMQ::QR_SERVER_CONTROL or OMQ::QR_SET_PROPERTY to set property values, OMQ::QR_DELETE_PROPERTY to delete property values

/api/v8/system/qorus-core/logger

This URI path provides ability to customize the qorus-core: Qorus Core Cluster Process process logger

DELETE /api/v8/system/qorus-core/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/qorus-core/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/qorus-core/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/qorus-core/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/qorus-master/logger

This URI path provides ability to customize the qorus: Qorus Cluster Master Process process logger

DELETE /api/v8/system/qorus-master/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/qorus-master/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/qorus-master/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/qorus-master/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/system/qorus-type-info

This REST URI path provides information regarding qorus data types

GET /api/v8/system/qorus-type-info

Returns a list of type info hashes

/api/v8/system/rbac

GET /api/v8/system/rbac

Description
Returns information about Role Based Access Control configuration and status
Return Value
This API returns a hash with the following keys:
  • loaded: the date/time Role Based Access Control information was loaded
  • users: the number of users cached
  • roles: the number of roles cached
  • permissions: a list of REST Permission Hash elements
  • enabled: True if Role Based Access Control is enabled
  • groups: the number of interface groups cached
  • providers: a hash of providers keyed by descriptive name; values are hashes with the following keys:
    • loaded: the date/time the provider was loaded
    • storage: a boolean value indicating whether the provides supports user-defined storage or not

PUT /api/v8/system/rbac?action=reload

Description
Reloads the all Role Based Access Control information (users, permissions, roles, groups) from the system schema
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_RELOAD_RBAC
See also
omq.system.reload-rbac()

/api/v8/system/scaling

This REST API path provides actions for scaling Qorus master containers under Kubernetes

PUT /api/v8/system/scaling?action=scaling

Description
Sets scaling parameters for qorus-master containers when Qorus is running under Kubernetes
  • scaling-min-replicas
  • scaling-max-replicas
  • scaling-cpu
  • scaling-memory
Return Value
This API returns the response of the Kubernetes rest request for updating the horizontal pod autoscaler for qorus-master containers.
Note
requires permission OMQ::QR_SCALING
Errors
  • 400 Bad Request: returned if Qorus is not running under Kubernetes
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation

/api/v8/system/sessions

This REST URI path provides actions and information related to Qorus application sessions

GET /api/v8/system/sessions

Description
Returns a list of hashes for sessions matched according to the arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ended_maxdate: (optional) give the upper date range for the session end date
  • ended_mindate: (optional) give the lower date range for the session end date
  • hostname: (optional) the hostname to search for
  • id: (optional) the session ID
  • key: (optional) the instance key name
  • limit: (optional) the maximum number of sessions to return
  • list: (optional) parsed with Qore::parse_boolean(); if True then a list of session names is returned
  • short: (optional) parsed with Qore::parse_boolean(); if True then a list of short strings of session names and descriptions is returned
  • started_maxdate: (optional) give the upper date range for the session start date
  • started_mindate: (optional) give the lower date range for the session start date
  • offset: (optional) the starting release to return (use when paging for example)
  • status: (optional) one or more session status values
  • url: (optional) the HTTP URL for the instance
  • version: (optional) the Qorus version string
Return Value
If list and short are not used, then this API returns list of hashes for sessions matched; each hash has the following keys:
  • id: the session ID
  • key: the instance key for the session
  • status: status of the session
  • hostname: the hostname hosting the Qorus process running the session
  • url: the primary URL for the application session
  • version: the Qorus version for the session
  • started: the date/time the session started
  • ended: the date/time the session ended

/api/v8/system/sqlcache

This REST API path provides actions and information related to the system SQL cache

Since
Qorus 3.1.0

GET /api/v8/system/sqlcache

Description
Returns information about the system cache
Arguments
This API takes the following hash argument:
  • system (*bool): if True, returns information about system objects as well (in the "omq" datasource)
Return Value
This API returns a SqlCacheSummaryInfo hash; keys have the following format:
  • any (SqlCacheTypeInfo): a hash of cache information keyed by datasource name, values are hashes keyed by SQL object type (ex: "tables")
    • count (int): the number of times accessed
    • created (date): the date/time the object was cached
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/system/sqlcache?action=clear

Description
Clears the SQL cache according to the arguments
Arguments
This API takes the following hash arguments:
  • datasource (*string): a string giving the datasource to clear all objects for
  • name (*string): the name of the object to clear; if this argument is given, then datasource must also be given
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/system/sqlcache?action=clearCache

Description
Clears the SQL cache according to the arguments.
See also
This API is equivalent to PUT /api/system/sqlcache?action=clear; see that documentation for details.

/api/v8/system/templates

GET /api/v8/system/templates

Description
Returns template information
Arguments
This API takes the following hash argument:
  • filter (*int): a bitfield of Expression Template Context Values to filter the results: 1: workflow context, 2: service context, 4: job context, 8: generic context, 7: interface context, 15: all contexts
Return Value
This API returns a value of type *list<TemplateInfo>: a list of template info hashes

/api/v8/system/ui

This REST URI path provides actions and information related to the system UI

GET /api/v8/system/ui

Description
Returns a list of child URI path components
Return Value
This API returns a list of child URI path components

/api/v8/system/ui/extensions

This REST URI path provides actions and information related to system UI extensions

GET /api/v8/system/ui/extensions

Description
Returns a list of hashes of information about UI extensions
Return Value
This API returns a list of REST System UI Extension Hash elements

GET /api/v8/system/ui/extensions?action=list

Description
Returns a list of hashes of information about UI extensions
See also
This API is equivalent to GET /api/system/ui/extensions; see that documentation for details.

/api/v8/system/ui/extensions/{name}

This REST URI path provides actions and information related to a specific system UI extension

GET /api/v8/system/ui/extensions/{name}

Description
Returns a hash of information about the current UI extension
Return Value
This API returns a REST System UI Extension Hash

/api/v8/system/userhttp

This REST URI path provides actions and information about user HTTP services.

GET /api/v8/system/userhttp

Description
Returns a hash keyed by resource type with values as lists of hashes of information about user-defined HTTP services
Return Value
The hash element in each list has the following keys:
  • title: the title of the HTTP service
  • url: the full URL to the service
  • service: the name of the service
  • version: the version of the service
  • serviceid: the service ID
Since
Qorus 4.0 returns an empty hash in case no data is available

/api/v8/system/{type}/logger

This URI path provides ability to customize Qorus system logger configurations

DELETE /api/v8/system/{type}/logger

Description
Delete system logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/system/{type}/logger

Description
Returns system logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
    • appenders: (list of hashes) list of appender hashes
  • interface_table_name: (string) system (audit, alert, monitoring, http, qorus-core, qorus-master, qdsp) type. If set means default logger

POST /api/v8/system/{type}/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/system/{type}/logger

Description
Set system logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/types

This REST URI path provides actions and information about Qorus types

GET /api/v8/types

Description
Returns a list of types
Arguments
This API takes no arguments
Return Value
This API returns a value of type list<TypeSummaryInfo>: a list of type information

POST /api/v8/types

Description
Creates a new type
Arguments
This API takes the following hash arguments:
  • path (string): the new path for the type
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the type
  • typeinfo (UndefinedHash): the new definition of the type
Return Value
This API returns a CreateTypeInfo hash with the following keys (a description of the new type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/types?action=create

Description
Creates a new type
Arguments
This API takes the following hash arguments:
  • path (string): the new path for the type
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the type
  • typeinfo (UndefinedHash): the new definition of the type
Return Value
This API returns a CreateTypeInfo hash with the following keys (a description of the new type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

,,,__entry_ /api/v8/types/,,,/{entry}

This REST URI path provides actions and information about Qorus type paths without a registered type

,,,__entry_ GET /api/v8/types/,,,/{entry}

Returns a description of the type

/api/v8/types/{type}

This REST URI path provides actions and information about a particular Qorus type

DELETE /api/v8/types/{type}

Description
Deletes the type
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a TypeDeletionInfo hash with the following key (information about the type that was deleted):
  • id (int): the ID of the type that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such type
Note
Requires one of the following permissions:

GET /api/v8/types/{type}

Returns a description of the type

PUT /api/v8/types/{type}

Description
Updates the current type
Arguments
This API takes the following hash arguments:
  • path (*string): the new path for the type; if not provided, the new path will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the type
  • typeinfo (*UndefinedHash): the new definition of the type
Return Value
This API returns an UpdateTypeInfo hash with the following keys (a description of the new type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/types/{type}?action=clone

Description
Clones the current type
Arguments
This API takes the following hash arguments:
  • path (*string): the new path for the type; if not provided, the new path will be generated
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the type
  • typeinfo (*UndefinedHash): the new definition of the type
Return Value
This API returns a CloneTypeInfo hash with the following keys (a description of the new type):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/types/{type}?action=file

Description
Returns the type as a file that can be saved

/api/v8/users

This REST URI path provides actions and information related to Qorus users

GET /api/v8/users

Description
Returns a list of hashes describing Qorus users
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST User Hash elements
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL

POST /api/v8/users

Description
Adds a user to the system
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • username: (required) the username to add
  • pass: (required) the password for the user
  • name: (required) the name of the user
  • roles: (optional) a single role or a list of roles to add to the user; note that the user must have at least the OMQ::QR_LOGIN permission to connect to the server
Return Value
This API returns a REST User Hash for the new user created
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: RBAC-ADD-USER-ERROR: invalid user, invalid role, invalid group
Note
See also

GET /api/v8/users?action=current

Description
Returns a hash describing the current calling user
Return Value
This API returns a REST User Hash

GET /api/v8/users?action=list

Description
Returns a list of hashes describing Qorus users
See also
This API is equivalent to GET /api/users; see that documentation for details.

/api/v8/users/{user}

This REST URI path provides actions and information related to a particular user

DELETE /api/v8/users/{user}

Description
Deletes the current user
Return Value
This API returns a hash with the following key:
  • info: a string describing the user deletion action
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_DELETE_USER
See also

GET /api/v8/users/{user}

Description
Returns a hash describing the current user
Return Value
This API returns a REST User Hash

PUT /api/v8/users/{user}

Description
Modifies the current user
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body); at least one of the following keys must be present:
  • pass: (string) password
  • name: (string) user description
  • storage: (hash) updated key-value pairs for server-side user storage; set a key to NOTHING to delete the key
  • roles: (list of strings) a comma-separated string will be split into a list; the new list will replace the current list unless the role names are preceded by "+" or "-", meaning add or remove a role, respectively (in which case all role names must be preceded by a "+" or "-"); to remove all roles for a user, send an empty list here
Return Value
This API returns the updated attributes of the user as a hash
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: RBAC-UPDATE-USER-ERROR: invalid user, no valid keys in hash, invalid role
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_MODIFY_USER
See also

PUT /api/v8/users/{user}?action=update

Description
Modifies the current user
See also
This API is equivalent to PUT /api/users/{user}; see that documentation for details.

/api/v8/valuemaps

This URI path provides actions and information related to Qorus value maps

GET /api/v8/valuemaps

Description
Returns a list of hashes describing value maps accessible by the current user
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Value Map Description Hash elements
Errors
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)

POST /api/v8/valuemaps

Description
Creates a new value map
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the value map
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the value map with markdown formatting
  • author (*list<string>): list of author names
  • exception (*bool): throw an exception when a value is not matched (default False)
  • groups (*list<string>): list of interface group names that this value map will be a member of
  • valuetype (string): the value type for the value map
  • dateformat (*string): the date format (when valuetype is date)
  • value-maps (ValueMapValues): a hash of keys where the values are value map values
    • value (auto): the value corresponding to the key
    • enabled (*bool): if the mapping is currently enabled
Return Value
This API returns a CreateValueMapInfo hash with the following keys (a description of the new value map):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/valuemaps?action=create

Description
Creates a new value map
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the value map
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the value map with markdown formatting
  • author (*list<string>): list of author names
  • exception (*bool): throw an exception when a value is not matched (default False)
  • groups (*list<string>): list of interface group names that this value map will be a member of
  • valuetype (string): the value type for the value map
  • dateformat (*string): the date format (when valuetype is date)
  • value-maps (ValueMapValues): a hash of keys where the values are value map values
    • value (auto): the value corresponding to the key
    • enabled (*bool): if the mapping is currently enabled
Return Value
This API returns a CreateValueMapInfo hash with the following keys (a description of the new value map):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/valuemaps?action=reload

Description
Reloads one or more value maps from the DB
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) a comma-separated string will be split into a list; the value map names or IDs to reset
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)
  • 409 Conflict: VALUE-MAP-ERROR: invalid or unknown value map
Note
requires permission OMQ::QR_VALUE_MAP_CONTROL or OMQ::QR_RELOAD_VALUE_MAP

PUT /api/v8/valuemaps?action=reloadAll

Description
Reloads all value maps accessible by the calling user
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_VALUE_MAP_CONTROL or OMQ::QR_RELOAD_VALUE_MAP

/api/v8/valuemaps/{id_or_name}

This URI path provides actions and information related to a specific value map

DELETE /api/v8/valuemaps/{id_or_name}

Description
Deletes the valuemap
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a ValueMapDeletionInfo hash with the following key (information about the valuemap that was deleted):
  • id (int): the ID of the valuemap that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such valuemap
Note
Requires one of the following permissions:

GET /api/v8/valuemaps/{id_or_name}

Description
Returns a hash describing the current value map
Return Value
This API returns a REST Value Map Description Hash
Errors
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)

PUT /api/v8/valuemaps/{id_or_name}

Description
Updates the current valuemap
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the value map
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the value map with markdown formatting
  • author (*list<string>): list of author names
  • exception (*bool): throw an exception when a value is not matched (default False)
  • groups (*list<string>): list of interface group names that this value map will be a member of
  • valuetype (*string): the value type for the value map
  • dateformat (*string): the date format (when valuetype is date)
  • value-maps (*ValueMapNewValues): a hash of keys where the values are value map values
    • value (auto): the value corresponding to the key
    • enabled (*bool): if the mapping is currently enabled
Return Value
This API returns an UpdateValueMapInfo hash with the following keys (a description of the new valuemap):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/valuemaps/{id_or_name}?action=clone

Description
Clones the current valuemap
Arguments
This API takes the following hash arguments:
  • name (*string): the new internal name for the value map
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the value map with markdown formatting
  • author (*list<string>): list of author names
  • exception (*bool): throw an exception when a value is not matched (default False)
  • groups (*list<string>): list of interface group names that this value map will be a member of
  • valuetype (*string): the value type for the value map
  • dateformat (*string): the date format (when valuetype is date)
  • value-maps (*ValueMapNewValues): a hash of keys where the values are value map values
    • value (auto): the value corresponding to the key
    • enabled (*bool): if the mapping is currently enabled
Return Value
This API returns a CloneValueMapInfo hash with the following keys (a description of the new valuemap):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

GET /api/v8/valuemaps/{id_or_name}?action=dump

Description
Returns a string giving the source of the value map as reconstructed from the database
Return Value
This API returns a string giving the source of the value map as reconstructed from the database
Errors
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)

GET /api/v8/valuemaps/{id_or_name}?action=file

Description
Returns the value map as a file that can be saved

GET /api/v8/valuemaps/{id_or_name}?action=lookup

Description
Looks up the mapping for the key given as an argument in the current value map and returns the mapped value
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • key: (required) the value map key to look up
Return Value
This API returns the value of the key
Errors
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)
  • 409 Conflict: VALUEMAP-LOOKUP-ERROR: missing key argument key

PUT /api/v8/valuemaps/{id_or_name}?action=reload

Description
Reloads the current value map from the DB
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)
Note
requires permission OMQ::QR_VALUE_MAP_CONTROL or OMQ::QR_RELOAD_VALUE_MAP

PUT /api/v8/valuemaps/{id_or_name}?action=value

Description
Creates or updates the mapping given as arguments in the current value map
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • key: (required) the value map key to create or update
  • value: (optional) the value to set; if not present, then the given key will be deleted
  • enabled: (optional) parsed with Qore::parse_boolean(); if True then the key is immediately usable; if not present the default is False
Return Value
This API returns a string describing the operation performed:
  • "DELETED": the key was deleted
  • "IGNORED": the key to be deleted did not exist
  • "CREATED": the key-value pair was created
  • "UPDATED": the key-value pair was updated
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)
Note
requires permission OMQ::QR_VALUE_MAP_CONTROL or OMQ::QR_MODIFY_VALUE_MAP

/api/v8/valuemaps/{id_or_name}/{key}

This URI path provides actions and information related to a specific value map value

GET /api/v8/valuemaps/{id_or_name}/{key}

Description
Returns the value of the current value map key
Return Value
This API returns the value of the current value map key
Errors
  • 403 Forbidden: VALUEMAP-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given value map (for more information, see Interface Groups)

/api/v8/workflows

This URI path allows workflows to be queried and for actions on multiple workflows to be performed; this is the URI path parent of workflow-specific actions as well.

GET /api/v8/workflows

Description
Returns information about workflows accessible to the calling user
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • deprecated: optional; parsed with Qore::parse_boolean(); if False then no deprecated workflows will be returned; default True
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of workflow names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings of workflow names and descriptions is returned
  • date: optional; parsed as a date; the minimum date for historical workflow order overview information; if omitted then defaults to the past 24 hours
  • sqlcache: optional; parsed with Qore::parse_boolean(); if False then no SQL cache will be used for historical info; default True
  • tags: optional; a hash of tags to match; only workflows matching at least one of the tags will be returned; use tag=value format as the value of this option
  • tag_case_insensitive: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons are made with case-insensitive comparisons
  • tag_partial_match: optional; parsed with Qore::parse_boolean(); if True then tag value comparisons succeed if the value given as the tag value appears anywhere in the object's tag of the same name
Return Value
If neither list nor short are used, then a list of hashes is returned, one element for each accessible workflow (depending on the calling users accessible interface groups); each hash in the returned list represents an accessible workflow as a REST Workflow Description Hash

POST /api/v8/workflows

Description
Creates a new workflow
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow
  • version (string): the new version for the workflow
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the workflow with markdown formatting
  • author (*list<string>): list of author names
  • steps (list<auto>): list of steps for the workflow
  • groups (*list<string>): list of interface group names that this workflow will be a member of
  • modules (*list<string>): list of workflow modules
  • remote (*bool): the remote status of the workflow
  • autostart (*int): how many workflow instances should be started automatically
  • sla_threshold (*int): the number in seconds for a workflow order to get a COMPLETE status without violating any SLA
  • max_instances (*int): the maximum number of execution instances that can be started for this workflow
  • classes (*list<string>): any library classes for this workflow
  • constants (*list<string>): any library constants for this workflow
  • functions (*list<string>): any library functions for this workflow
  • mappers (*list<string>): any mappers for this workflow
  • vmaps (*list<string>): any value maps for this workflow
  • errors (*list<string>): any error sets for this workflow
  • options (*UndefinedHash): any options for this workflow
  • keylist (*list<string>): workflow order keys
  • statuses (*UndefinedHash): user-defined order status values
  • tags (*UndefinedHash): user-defined tags
  • source (*string): workflow class source
  • base-class-name (*string): the base class name for the workflow (must inherit QorusWorkflow)
  • class-name (*string): the workflow code's class name
  • lang (*string): the language for the workflow class code, one of "qore" (the default), "python", or "java"
  • config-item-values (*list<UndefinedHash>): a list of config items and values for the workflow
  • staticdata-type (*UndefinedHash): the static data type definition for the workflow
  • system-options (*UndefinedHash): system options for the workflow
Return Value
This API returns a CreateWorkflowInfo hash with the following keys (a description of the new workflow):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/workflows?action=create

Description
Creates a new workflow
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow
  • version (string): the new version for the workflow
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (string): the new description for the workflow with markdown formatting
  • author (*list<string>): list of author names
  • steps (list<auto>): list of steps for the workflow
  • groups (*list<string>): list of interface group names that this workflow will be a member of
  • modules (*list<string>): list of workflow modules
  • remote (*bool): the remote status of the workflow
  • autostart (*int): how many workflow instances should be started automatically
  • sla_threshold (*int): the number in seconds for a workflow order to get a COMPLETE status without violating any SLA
  • max_instances (*int): the maximum number of execution instances that can be started for this workflow
  • classes (*list<string>): any library classes for this workflow
  • constants (*list<string>): any library constants for this workflow
  • functions (*list<string>): any library functions for this workflow
  • mappers (*list<string>): any mappers for this workflow
  • vmaps (*list<string>): any value maps for this workflow
  • errors (*list<string>): any error sets for this workflow
  • options (*UndefinedHash): any options for this workflow
  • keylist (*list<string>): workflow order keys
  • statuses (*UndefinedHash): user-defined order status values
  • tags (*UndefinedHash): user-defined tags
  • source (*string): workflow class source
  • base-class-name (*string): the base class name for the workflow (must inherit QorusWorkflow)
  • class-name (*string): the workflow code's class name
  • lang (*string): the language for the workflow class code, one of "qore" (the default), "python", or "java"
  • config-item-values (*list<UndefinedHash>): a list of config items and values for the workflow
  • staticdata-type (*UndefinedHash): the static data type definition for the workflow
  • system-options (*UndefinedHash): system options for the workflow
Return Value
This API returns a CreateWorkflowInfo hash with the following keys (a description of the new workflow):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/workflows?action=decAutostart

Description
Decrements the autostart value on one or more workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to modify; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • arg: the workflow ID or name
  • updated: True or False
  • autostart: the new autostart value for the workflow
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • info: info about the workflow update action or a reason why the request failed
  • [stopped]: the number of execution instances stopped
Errors
  • 409 Conflict: WORKFLOW-SETAUTOSTART-ERROR: missing ids argument; autostart value cannot be negative
Note

GET /api/v8/workflows?action=defaultLogger

Description
Returns default logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services). If set means default logger

POST /api/v8/workflows?action=defaultLogger

Description
Create default Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/workflows?action=defaultLogger

Description
Set logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

DELETE /api/v8/workflows?action=defaultLogger

Description
Delete logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/workflows?action=defaultLoggerAppenders

Description
Return all logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

DELETE /api/v8/workflows?action=defaultLoggerAppenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

POST /api/v8/workflows?action=defaultLoggerAppenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/workflows?action=defaultLoggerAppenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/workflows?action=disable

Description
Disables one or more enabled workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to disable; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances disabled
  • details: a list of hashes providing details of the individual workflow disable actions with the following keys
    • arg: the workflow ID or name
    • stopped: True or False
    • [count]: the number of execution instances stopped
    • [workflowid]: the workflow ID
    • [name]: the workflow name
    • [version]: the workflow version
    • info: info about the workflow disable action or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-DISABLE-ERROR: missing ids argument
Note

PUT /api/v8/workflows?action=enable

Description
Enables one or more disabled workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to enable; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • arg: the workflow ID or name
  • enabled: True or False
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • info: info about the workflow enable action or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-ENABLE-ERROR: missing ids argument
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: disabled workflows cannot be enabled while the system is shutting down
Note

PUT /api/v8/workflows?action=incAutostart

Description
Increments the autostart value on one or more workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to modify; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • arg: the workflow ID or name
  • updated: True or False
  • autostart: the new autostart value for the workflow
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • info: info about the workflow update action or a reason why the request failed
  • [started]: the number of execution instances started
Errors
  • 409 Conflict: WORKFLOW-SETAUTOSTART-ERROR: missing ids argument; cannot set a positive autostart value on a workflow with the deprecated flag set
Note

GET /api/v8/workflows?action=list

Description
Returns information about workflows accessible to the calling user.
See also
This API is equivalent to GET /api/workflows; see that documentation for details.

GET /api/v8/workflows?action=listErrors

Description
Returns information about workflow order errors corresponding to the search arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • workflow_instanceid: limit the search to one or more workflow_instanceids
  • error_instanceid: mit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • workflowid: limit the search to one or more workflowids
  • workflowstatus: limit the search to workflow instances with the given status value(s)
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

GET /api/v8/workflows?action=processingSummary

Description
Returns information about workflow processing.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • mindate: (required) minimum date
  • maxdate: maximum date
  • wfids: optional workflow IDs
  • seconds: if True then the performance values will be returned as arbitrary-precision numeric values representing seconds, otherwise they will be returned as relative date/time values
  • global: if True then all workflows will be combined into an overall processing report, if False then each workflow gets a separate line in the output
  • grouping: (optional) possible values for reporting performance statistics:
    • "hourly": hourly grouping
    • "daily": daily grouping
    • "monthly": monthly grouping
    • "yearly": yearly grouping
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • workflowid: the workflow ID
  • name: the workflow name
  • version: the workflow version
  • count: the number of workflow orders in the period
  • minstarted: the minimum workflow order start date
  • maxcompleted: the maximum workflow order completion date (if any)
  • minduration: the minimum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • avgduration: the average total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • maxduration: the maximum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • minprocessing: the minimum order processing time for workflow orders in the period (starting from when then order was first processed)
  • avgprocessing: the average order processing time for workflow orders in the period (starting from when then order was first processed)
  • maxprocessing: the maximum order processing time for workflow orders in the period (starting from when then order was first processed)
Errors
  • 409 Conflict: ARGUMENT-ERROR: missing mindate

PUT /api/v8/workflows?action=reset

Description
Resets one or more workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to reset; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances disabled
  • details: a list of hashes providing details of the individual workflow reset actions with the following keys
    • arg: the workflow ID or name
    • reset: True or False
    • [workflowid]: the workflow ID
    • [name]: the workflow name
    • [version]: the workflow version
    • info: info about the workflow reset action or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-RESET-ERROR: missing ids argument
Note

PUT /api/v8/workflows?action=resetAll

Description
Resets all cached and running workflow execution instances accessible by the calling user.
Return Value
This API returns a list of hashes of affected workflows with the following keys:
  • name: the name of the workflow that was reset
  • version: the version of the workflow that was reset
  • workflowid: the workflow ID of the workflow that was reset
  • count: the number of workflow execution instances affected
Note

PUT /api/v8/workflows?action=setAutostart

Description
Sets the autostart value on one or more workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to modify; a comma-separated string will be split into a list
  • autostart: (required) an integer value giving the new autostart value for the workflow(s)
Return Value
This API returns a hash with the following keys:
  • arg: the workflow ID or name
  • updated: True or False
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • info: info about the workflow update action or a reason why the request failed
  • [started]: the number of execution instances started
Note
the autostart cannot be set over Workflow Max Instances Parameter; in case Workflow Max Instances Parameter is reached the autostart value is set to Workflow Max Instances Parameter and this number is returned in started
Errors
  • 409 Conflict: WORKFLOW-SETAUTOSTART-ERROR: missing ids or autostart argument; autostart value is negative; cannot set a positive autostart value on a workflow with the deprecated flag set
Note

PUT /api/v8/workflows?action=setDeprecated

Description
Sets or removes the deprecated flag on one or more workflows.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to modify; a comma-separated string will be split into a list
  • deprecated: (required) a value (processed with Qore::parse_boolean()) indicating whether or not the workflows should have their deprecated flag set (True) or removed (False)
Return Value
This API returns a hash with the following keys:
  • arg: the workflow ID or name
  • updated: True or False
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • [stopped]: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • info: info about the workflow update action or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-SETDEPRECATED-ERROR: missing ids or deprecated argument
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: disabled workflows cannot be enabled while the system is shutting down
Note

PUT /api/v8/workflows?action=start

Description
Manually starts one or more workflow execution instances.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to start; a comma-separated string will be split into a list
Return Value
This API returns a list of hashes with the following keys:
  • arg: the workflow ID or name
  • started: True or False
  • [exec_id]: the workflow execution ID (when started = True)
  • [workflowid]: the workflow ID
  • [name]: the workflow name
  • [version]: the workflow version
  • info: info about the workflow start or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-START-ERROR: missing ids argument
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: workflows cannot be started while the system is shutting down
Note
Deprecated:
Workflow execution instances should not be manually started; they should be started by the system based on their autostart values and enabled and disabled for operational reasons; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances

PUT /api/v8/workflows?action=stop

Description
Manually stops one or more workflow execution instances.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ids: (required) one or more workflow names or IDs to stop; a comma-separated string will be split into a list
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances stopped
  • workflows: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • details: a list of hashes providing details of the individual workflow stop actions with the following keys
    • arg: the workflow ID or name
    • stopped: True or False
    • [count]: the number of execution instances stopped
    • [workflowid]: the workflow ID
    • [name]: the workflow name
    • [version]: the workflow version
    • info: info about the workflow stop action or a reason why the request failed
Errors
  • 409 Conflict: WORKFLOW-STOP-ERROR: missing ids argument
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances
Note

PUT /api/v8/workflows?action=stopAll

Description
Stops all workflow execution instances.
Return Value
This API returns a hash with the following keys:
  • count: number of workflow execution instances stopped
  • workflows: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • msg: a descriptive message about the workflows stopped
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances
Note

/api/v8/workflows/{id_or_name}

This REST URI path provides actions and information about a particular workflow.

DELETE /api/v8/workflows/{id_or_name}

Description
Deletes the workflow
Arguments
This API takes the following hash argument:
  • cascade (*bool): force-delete the object and update all dependent objects; can break those objects
Return Value
This API returns a WorkflowDeletionInfo hash with the following key (information about the workflow that was deleted):
  • id (int): the ID of the workflow that was deleted
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no such workflow
Note
Requires one of the following permissions:

GET /api/v8/workflows/{id_or_name}

Description
Returns information about the current workflow
Arguments
Return Value
This API returns a WorkflowDefinitionInfoV3 hash with the following keys (information about the current workflow):
  • workflowid (int): the workflow ID
  • name (string): the workflow name
  • version (string): the workflow version
  • display_name (*string): the display name
  • short_desc (*string): the short description in plain text
  • description (*string): the workflow description in markdown
  • author (*string): the workflow author
  • remote (bool): if True, the workflow will run as a remote qwf process, otherwise it runs internally in the qorus-core process
  • manual_remote (bool): set if the manual value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • onetimeinit_func_instanceid (*int): the onetimeinit function ID for the workflow (if defined)
  • attach_func_instanceid (*int): the attach function ID for the workflow (if defined)
  • detach_func_instanceid (*int): the detach function ID for the workflow (if defined)
  • errorfunction_instanceid (*int): the error function ID for the workflow (if defined)
  • errhandler_func_instanceid (*int): the error handler function ID for the workflow (if defined)
  • has_detach (bool): True if the workflow has detach logic
  • created (date): the workflow creation date
  • modified (date): the workflow last modified date
  • autostart (int): the workflow autostart value
  • manual_autostart (bool): set if the autostart value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • sla_threshold (int): the workflow SLA threshold value
  • manual_sla_threshold (bool): a boolean flag set if the sla_threshold value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • enabled (bool): a boolean flag indicating if the workflow is enabled or not; disabled workflows cannot be started
  • deprecated (bool): a boolean flag indicating if the workflow is deprecated or not; deprecated workflows are not displayed by default in the UI
  • language (*string): the programming language for the workflow's class (if any)
  • code (*string): the source code for the workflow's class (if any)
  • source (*string): the source for the workflow definition
  • line (*int): the line number offset in source for the workflow definition
  • tags (*UndefinedHash): any tags for the workflow
  • order_key_map (*Set): set of order keys in hash form
    • key (bool): bool value
  • keylist (*list<string>): a list of workflow order keys
  • stepmap (StringMap): a hash where keys are step IDs and values are step names
    • key (string): string value
  • steps (IntListMap): a hash of step dependencies, where keys are step IDs and values are lists of step IDs that must preceed the step ID given as a key
    • key (*list<int>): *list<int> value
  • segment (list<SegmentInfo>): a list of segment description hashes, where each segment hash has the following keys:
  • stepseg (*IntMap): maps step IDs to segment numbers
    • key (int): int value
  • lib (*LibraryInfo): information about any referenced Qorus objects
    • functions (*list<LibraryDetailInfo>): a list of function objects (can be empty)
    • classes (*list<LibraryDetailInfo>): a list of class objects (can be empty)
    • constants (*list<LibraryDetailInfo>): a list of constant objects (can be empty)
    • pipelines (*list<NameIdInfo>): a list of pipeline objects (can be empty)
    • fsm (*list<NameIdInfo>): a list of FSM objects (can be empty)
  • mappers (*list<MapperInfo>): a list of mappers associated with the workflow
  • vmaps (*list<VMapInfo>): a list of value maps associated with the workflow
  • stepinfo (list<WorkflowStepInfo>): a list of hashes giving information about workflow steps
  • wffuncs (list<WorkflowFuncInfo>): a list of workflow-level functions (may be empty)
  • options (list<OptionInfoHash>): a list option information hashes
  • config (*ConfigItemSummarySetInfo): a hash of configuration item info keyed by config item name
    • name (string): the name of the configuration item
    • prefix (*string): the prefix of the configuration item
    • type (string): the data type of the configuration item
    • desc (string): the description of the configuration item
    • default_value (auto): the default value of the configuration item
    • value (auto): the value of the configuration item
    • strictly_local (bool): if the configuration item is defined strictly on local level
    • is_set (bool): True if the value is set otherwise False
    • is_templated_string (bool): True if the value is a templated string that can be later expanded
    • config_group (string): the group of the configuration item
    • allowed_values (*list<auto>): the list of allowed values for the configuration item if defined
    • level (string): the level from where the value is obtained (interface level (e.g. "job:1", "job:2")
  • global_config (*GlobalConfigItemSetInfo): a hash of configuration item info keyed by config item name
    • allowed_values (*list<auto>): the list of allowed values for the configuration item if defined
    • is_set (bool): True if the value is set otherwise False
    • is_templated_string (bool): True if the value is a templated string that can be later expanded
    • prefix (*string): the prefix of the configuration item
    • type (string): the data type of the configuration item
    • value (auto): the value of the configuration item
  • exec (*list<ExecInstanceInfoV3>): a list of hashes describing any workflow execution instances running for this workflow
  • COMPLETE (*int): number of workflow orders with status COMPLETE
  • INCOMPLETE (*int): number of workflow orders with status INCOMPLETE
  • WAITING (*int): number of workflow orders with status WAITING
  • EVENT-WAITING (*int): number of workflow orders with status EVENT-WAITING
  • ASYNC-WAITING (*int): number of workflow orders with status ASYNC-WAITING
  • RETRY (*int): number of workflow orders with status RETRY
  • ERROR (*int): number of workflow orders with status ERROR
  • CANCELED (*int): number of workflow orders with status CANCELED
  • BLOCKED (*int): number of workflow orders with status BLOCKED
  • IN-PROGRESS (*int): number of workflow orders with status IN-PROGRESS
  • SCHEDULED (*int): number of workflow orders with status SCHEDULED
  • READY (*int): number of workflow orders with status READY
  • TOTAL (*int): number of workflow orders in all statuses
  • process (*WorkflowProcessExecInfo): present when remote is True
    • id (string): the unique process ID in the cluster
    • node (string): the node name where the process is running
    • host (string): the hostname where the process is running
    • pid (int): the PID on the host
    • log_pipe (*string): any log pipe for the process
    • port (*int): any port number for the process
    • prometheus_port (*int): any port number for communicating with Prometheus
    • urls (list<string>): a list of ZeroMQ URLs for the process
    • status (*int): the process's status code
    • status_string (*string): the process's status as a string
    • restarted (*bool): indicates if the process has been restarted
    • priv (*int): the amount of private memory of the process in bytes
    • rss (*int): the resident size of the process in bytes
    • vsz (*int): the virtual size of the process in bytes
    • priv_str (*string): a string description of the priv value
    • pct (*int): the percentage of main memory taken up by the process on the node
    • socket_path (*string): any socket path for the process
    • wfname (*string): the workflow name
    • wfversion (*string): the workflow version
    • wfid (*int): the workflow ID
    • sessionid (*int): the workflow session ID
  • exec_count (int): the number of elements in the exec list
  • order_stats (*list<UndefinedHash>): a list of workflow order processing statistics; list values are OrderSummaryOutputInfo hashes for the given workflow
  • workflow_modules (*list<string>): any modules associated with the workflow
  • alerts (*list<AlertInfo>): a list of alerts raised against the workflow
  • connections (*list<InterfaceConnectionInfo>): a list of connection objects that this workflow depends on
  • groups (*list<GroupInfo>): a list of interface groups that the workflow belongs to

PUT /api/v8/workflows/{id_or_name}

Description
Updates the current workflow
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow
  • version (*string): the new version for the workflow
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the workflow with markdown formatting
  • author (*list<string>): list of author names
  • steps (*list<auto>): list of steps for the workflow
  • groups (*list<string>): list of interface group names that this workflow will be a member of
  • modules (*list<string>): list of workflow modules
  • remote (*bool): the remote status of the workflow
  • autostart (*int): how many workflow instances should be started automatically
  • sla_threshold (*int): the number in seconds for a workflow order to get a COMPLETE status without violating any SLA
  • max_instances (*int): the maximum number of execution instances that can be started for this workflow
  • classes (*list<string>): any library classes for this workflow
  • constants (*list<string>): any library constants for this workflow
  • functions (*list<string>): any library functions for this workflow
  • mappers (*list<string>): any mappers for this workflow
  • vmaps (*list<string>): any value maps for this workflow
  • errors (*list<string>): any error sets for this workflow
  • options (*UndefinedHash): any options for this workflow
  • keylist (*list<string>): workflow order keys
  • statuses (*UndefinedHash): user-defined order status values
  • tags (*UndefinedHash): user-defined tags
  • source (*string): workflow class source
  • base-class-name (*string): the base class name for the workflow (must inherit QorusWorkflow)
  • class-name (*string): the workflow code's class name
  • lang (*string): the language for the workflow class code, one of "qore" (the default), "python", or "java"
  • config-item-values (*list<UndefinedHash>): a list of config items and values for the workflow
  • staticdata-type (*UndefinedHash): the static data type definition for the workflow
  • system-options (*UndefinedHash): system options for the workflow
Return Value
This API returns an UpdateWorkflowInfo hash with the following keys (a description of the new workflow):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}?action=clone

Description
Clones the current workflow
Arguments
This API takes the following hash arguments:
  • name (string): the new internal name for the workflow
  • version (*string): the new version for the workflow
  • display_name (*string): the new display name
  • short_desc (*string): the plain-text short description
  • desc (*string): the new description for the workflow with markdown formatting
  • author (*list<string>): list of author names
  • steps (*list<auto>): list of steps for the workflow
  • groups (*list<string>): list of interface group names that this workflow will be a member of
  • modules (*list<string>): list of workflow modules
  • remote (*bool): the remote status of the workflow
  • autostart (*int): how many workflow instances should be started automatically
  • sla_threshold (*int): the number in seconds for a workflow order to get a COMPLETE status without violating any SLA
  • max_instances (*int): the maximum number of execution instances that can be started for this workflow
  • classes (*list<string>): any library classes for this workflow
  • constants (*list<string>): any library constants for this workflow
  • functions (*list<string>): any library functions for this workflow
  • mappers (*list<string>): any mappers for this workflow
  • vmaps (*list<string>): any value maps for this workflow
  • errors (*list<string>): any error sets for this workflow
  • options (*UndefinedHash): any options for this workflow
  • keylist (*list<string>): workflow order keys
  • statuses (*UndefinedHash): user-defined order status values
  • tags (*UndefinedHash): user-defined tags
  • source (*string): workflow class source
  • base-class-name (*string): the base class name for the workflow (must inherit QorusWorkflow)
  • class-name (*string): the workflow code's class name
  • lang (*string): the language for the workflow class code, one of "qore" (the default), "python", or "java"
  • config-item-values (*list<UndefinedHash>): a list of config items and values for the workflow
  • staticdata-type (*UndefinedHash): the static data type definition for the workflow
  • system-options (*UndefinedHash): system options for the workflow
Return Value
This API returns a CloneWorkflowInfo hash with the following keys (a description of the new workflow):
  • action (string): the action performed
  • id (int): the object ID
  • obj (UndefinedHash): the object
  • tags (*UndefinedHash): any tags for the object or sent with the request
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}?action=createOrder

Description
Creates a workflow order data instance for the current workflow with the data passed as arguments. To ensure that a given workflow order is only created once for a given unique key value, make sure your workflow defines order keys, and use one of the following options to guarantee the uniqueness of the order: - global_unique_key - workflow_specific_unique_key - workflow_unique_key
Arguments
This API takes the following hash arguments:
  • external_order_instanceid (*string): the external order instance ID for the workflow data; either this key or staticdata is required
  • dynamicdata (*UndefinedHash): the initial dynamic data for the order
  • global_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys (*UndefinedHash): a hash of order keys for the order
  • parent_workflow_instanceid (*int): a loosely-coupled workflow that will be marked as the parent of this workflow
  • priority (*int): the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • scheduled (*date): the earliest date and time the order can be processed; if this date is given as a future date/time value and a OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::StatReady
  • sensitive_data (*SensitiveDataSetInfo): a hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values
    • key (SensitiveDataKeyInfo): SensitiveDataKeyInfo value
  • staticdata (UndefinedHash): the static data for the order; either this key or external_order_instanceid is required
  • status (*string): the initial order status (default OMQ::StatReady); must be either OMQ::StatReady or OMQ::StatBlocked
  • workflow_specific_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); if this key already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
Return Value
This API returns a WorkflowOrderCreateInfo hash with the following key (describes the workflow order created):
  • workflow_instanceid (string): the workflow instance ID of the order created
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing create order request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=decAutostart

Description
Decrements the autostart value for the current workflow; if the workflow is running, a running workflow execution instance is stopped immediately
Arguments
Return Value
This API returns a WorkflowSetAutostartResultInfo hash with the following keys (information about the result of the operation):
  • updated (bool): a flag indicating if a change was actually made or not
  • autostart (int): the new autostart value
  • info (string): a string providing information about the workflow update action
  • started (int): if negative, then it is the number of execution instances stopped
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=disable

Description
Disables the current workflow if it is enabled; if the workflow is already disabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a WorkflowUpdateResultInfo hash with the following keys (information about the result of the operation):
  • workflowid (int): the workflow ID
  • name (string): the workflow name
  • version (string): the workflow version
  • info (string): a string providing information about the workflow update action
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=enable

Description
Enables the current workflow if it is disabled; if the workflow is already enabled, the action is reported as successful anyway
Arguments
Return Value
This API returns a WorkflowUpdateResultInfo hash with the following keys (information about the result of the operation):
  • workflowid (int): the workflow ID
  • name (string): the workflow name
  • version (string): the workflow version
  • info (string): a string providing information about the workflow update action
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}?action=execSynchronous

Description
Creates a new order for the current workflow and executes it synchronous mode. This API call will return only after the workflow order reaches a COMPLETE or ERROR state, unless the system or the workflow order data instance are manually stopped while the workflow order data instance is being processed, in which case other statuses can be returned. To ensure that a given workflow order is only created once for a given unique key value, make sure your workflow defines order keys, and use one of the following options to guarantee the uniqueness of the order: - global_unique_key - workflow_specific_unique_key - workflow_unique_key
Arguments
This API takes the following hash arguments:
  • external_order_instanceid (*string): the external order instance ID for the workflow data; either this key or staticdata is required
  • dynamicdata (*UndefinedHash): the initial dynamic data for the order
  • global_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys (*UndefinedHash): a hash of order keys for the order
  • parent_workflow_instanceid (*int): a loosely-coupled workflow that will be marked as the parent of this workflow
  • priority (*int): the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • sensitive_data (*SensitiveDataSetInfo): a hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values
    • key (SensitiveDataKeyInfo): SensitiveDataKeyInfo value
  • staticdata (UndefinedHash): the static data for the order; either this key or external_order_instanceid is required
  • workflow_specific_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); if this key already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
Return Value
This API returns a WorkflowOrderExecutionInfo hash with the following keys (describes the workflow order created):
  • workflow_instanceid (string): the workflow instance ID of the order created
  • status (string): the status of the order after synchronous order processing
  • dynamicdata (*UndefinedHash): the dynamic data of the workflow order instance
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing create order request
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}?action=execSynchronousAsync

Description
Creates a new order for the current workflow and executes it synchronous mode in a background thread. The call returns as soon as the order instance has been created and returns the workflow_instanceid for the new workflow order as well as the new execution ID. To ensure that a given workflow order is only created once for a given unique key value, make sure your workflow defines order keys, and use one of the following options to guarantee the uniqueness of the order: - global_unique_key - workflow_specific_unique_key - workflow_unique_key
Arguments
This API takes the following hash arguments:
  • external_order_instanceid (*string): the external order instance ID for the workflow data; either this key or staticdata is required
  • dynamicdata (*UndefinedHash): the initial dynamic data for the order
  • global_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the order (across all workflows regardless of workflowid, name, or version); if this key already exists for any order in the system, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • orderkeys (*UndefinedHash): a hash of order keys for the order
  • parent_workflow_instanceid (*int): a loosely-coupled workflow that will be marked as the parent of this workflow
  • priority (*int): the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • sensitive_data (*SensitiveDataSetInfo): a hash of sensitive data information for the workflow; this key can only be used when submitting the data over a secure (encrypted) connection; the keys are sensitive data key types, values are hashes keyed by sensitive data values
    • key (SensitiveDataKeyInfo): SensitiveDataKeyInfo value
  • staticdata (UndefinedHash): the static data for the order; either this key or external_order_instanceid is required
  • workflow_specific_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflowid (which matches a unique name and workflow version); if this key already exists for an order with the target workflowid, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
  • workflow_unique_key (*UndefinedHash): a hash giving one or more unique order keys for the particular workflow by name only (across all workflows with the same name regardless of version); if this key already exists for a workflow order with the same name, then the order creation will fail with a DUPLICATE-ORDER-KEY error; the hash key must be a valid order key, and the value is the unique key value; this value will also be created as an order key
Return Value
This API returns a WorkflowOrderExecutionAsyncInfo hash with the following keys (describes the workflow order created):
  • workflow_instanceid (int): the workflow instance ID of the order created
  • execid (int): the synchronous workflow execution instance ID
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing create order request
Note
Requires one of the following permissions:

GET /api/v8/workflows/{id_or_name}?action=file

Description
Returns the workflow as a file that can be saved

PUT /api/v8/workflows/{id_or_name}?action=incAutostart

Description
Increments the autostart value for the current workflow; if the workflow is eligible to be started, an additional workflow execution instance is started immediately
Arguments
Return Value
This API returns a WorkflowSetAutostartResultInfo hash with the following keys (information about the result of the operation):
  • updated (bool): a flag indicating if a change was actually made or not
  • autostart (int): the new autostart value
  • info (string): a string providing information about the workflow update action
  • started (int): if negative, then it is the number of execution instances stopped
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}?action=kill

Description
Kills a remote workflow cluster process
Arguments
Return Value
This API returns a KillResultInfo hash with the following keys (information about the result of the operation):
  • status (string): either "OK" or "ERR"
  • code (int): the return code of the kill() command: 0 if successful, non-zero if not
Errors
  • 403 Forbidden: access or authorization error
  • 404 Not Found: if no remote process is running for the workflow
Note
Requires one of the following permissions:

GET /api/v8/workflows/{id_or_name}?action=listErrors

Description
Returns information about workflow order errors corresponding to the search arguments for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • workflow_instanceid: limit the search to one or more workflow_instanceids
  • error_instanceid: mit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • workflowstatus: limit the search to workflow instances with the given status value(s)
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

POST /api/v8/workflows/{id_or_name}?action=lockUserInteractionStep

Description
Locks the next available queue entry eligible for user interaction for the named step and returns the step information or a 404 Not Found error if no such data is available
Arguments
This API takes the following hash arguments:
  • stepid (*int): the ID of the step to acquire user interaction data from; either this or stepname is required
  • stepname (*string): the name of the step to acquire user interaction data from; either this or stepid is required
Return Value
This API returns a WorkflowLockUseInteractionStepResultInfo hash with the following keys (information about the result of the operation):
  • workflow_instanceid (int): the workflow order instance ID
  • stepid (int): the step ID of the step
  • ind (int): the step instance index number
  • queuekey (string): the queue key ID
  • queueid (int): the ID of the async queue
  • queuename (string): the name of the async queue
  • data (*UndefinedHash): any step data already present
Errors
  • 400 Bad Request: missing or invalid arguments
  • 403 Forbidden: access or authorization error
  • 404 Not Found: no data available on the queue to lock
Note
Requires one of the following permissions:

GET /api/v8/workflows/{id_or_name}?action=options

Description
Returns options set on the current workflow.
Return Value
This API returns NOTHING if no options are set, otherwise a hash of workflow options.

PUT /api/v8/workflows/{id_or_name}?action=reset

Description
Resets and reloads the current workflow by reloading the configuration for the current workflow in the metadata cache; if there are any running execution instances, then the reset will cause the workflow configuration to be reset on their next iteration.
Arguments
Return Value
This API returns a value of type string: the value "OK"
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=setAutostart

Description
Sets the autostart attribute for the current workflow which specifies the targeted numbe of workflow execution instances to be running for the workflow at one time. If the new autostart value is higher than current one, and the workflow is eligible to be started, then new workflow execution instances will be started automatically, while reducing a workflow's autostart value will result in workflow execution instances being stopped immediately.
Arguments
This API takes the following hash argument:
  • autostart (int): the new autostart value for the workflow
Return Value
This API returns a WorkflowSetAutostartResultInfo hash with the following keys (information about the result of the operation):
  • updated (bool): a flag indicating if a change was actually made or not
  • autostart (int): the new autostart value
  • info (string): a string providing information about the workflow update action
  • started (int): if negative, then it is the number of execution instances stopped
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=setDeprecated

Description
Sets or removes the deprecated flag on the current workflow.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • deprecated: (required) a value (processed with Qore::parse_boolean()) indicating whether or not the workflow should have its deprecated flag set (True) or removed (False)
Return Value
This API returns a hash with the following keys:
  • updated: True or False
  • stopped: a hash keyed by workflow description where the values are the lists of all execution instance IDs stopped for that workflow
  • info: info about the workflow update action
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: WORKFLOW-SETDEPRECATED-ERROR: missing deprecated argument
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: disabled workflows cannot be enabled while the system is shutting down
Note
  • requires permission OMQ::QR_WORKFLOW_CONTROL
  • workflows set to deprecated are immediately stopped; workflows no longer deprecated are immediately started if their autostart value is greater than zero

PUT /api/v8/workflows/{id_or_name}?action=setOptions

Description
Sets workflow options for the current workflow. If the workflow has an option list and any of the options are not valid for that workflow, an exception will be thrown, however, even if an exception is thrown due to an option error, all other options will still be set.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: a hash of options to set against the workflow; if the value of this key is a string, then it is first parsed with Util::parse_to_qore_value(), which should then return a hash
Return Value
This API returns "OK" upon successful execution
Errors
  • 400 Bad Request: missing "options" argument or "options" is not a hash (or string parsed to a hash with Util::parse_to_qore_value())
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: WORKFLOW-OPTION-ERROR: invalid option for workflow or option cannot be overridden at the workflow level
Note

PUT /api/v8/workflows/{id_or_name}?action=setRemote

Description
Sets the 'remote' attribute for the current workflow, determining if it will run in a separate remote qwf process or locally in qorus-core. Workflows updated with this API are disabled before the change and reenabled after the change.
Arguments
This API takes the following hash argument:
  • remote (bool): the new remote value for the workflow
Return Value
This API returns a WorkflowSetRemoteResultInfo hash with the following keys (information about the result of the operation):
  • updated (bool): a flag indicating if a change was actually made or not
  • remote (bool): the new remote value
  • info (string): a string providing information about the workflow update action
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=setSla

Description
Sets the SLA attribute for the current workflow which specifies the maximum targeted time a workflow order should get a final status (being one of COMPLETE or CANCELED)
Arguments
This API takes the following hash argument:
  • sla (int): a value giving the new SLA timeout value as an integer in seconds for the workflow
Return Value
This API returns a WorkflowSetSlaResultInfo hash with the following keys (information about the result of the operation):
  • updated (bool): a flag indicating if a change was actually made or not
  • sla (int): the new SLA value as a positive integer in seconds
  • info (string): a string providing information about the workflow update action
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing the request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}?action=start

Description
Manually starts one or more workflow execution instances for the current workflow.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • count: (optional) the number of execution instances to start; defaults to 1
  • mode: (optional) the workflow execution instance mode; defaults to OMQ::WM_Normal (also may be OMQ::WM_Recovery)
Return Value
This API returns a list of hashes with the following keys:
  • name: the workflow name
  • version: the workflow version
  • ids: the execution IDs started
  • exec: a list of execution instance hashes running for this workflow
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: cannot start new workflows because the system is shutting down
Note
Deprecated:
Workflow execution instances should not be manually started; they should be started by the system based on their autostart values and enabled and disabled for operational reasons; use PUT /api/workflows/{id_or_name}?action=enable and PUT /api/workflows/{id_or_name}?action=disable instead of manually starting and stopping workflow execution instances

PUT /api/v8/workflows/{id_or_name}?action=stop

Description
Manually stops all execution instances for the current workflow.
Return Value
This API returns "OK" upon successful execution
Deprecated:
Workflow execution instances should not be manually stopped; they should be disabled instead; use PUT /api/workflows?action=enable and PUT /api/workflows?action=disable instead of starting and stopping workflow execution instances
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/workflows/{id_or_name}/config

This REST URI path provides actions and information related to Qorus workflow configuration item values

GET /api/v8/workflows/{id_or_name}/config

Description
Returns a list of workflow configuration item values for the workflow
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": the current value of the configuration item on this level
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

POST /api/v8/workflows/{id_or_name}/config

Description
Creates the value for the given step configuration items on the workflow level
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: the name of the configuration item
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the workflow configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

GET /api/v8/workflows/{id_or_name}/config?action=yaml

Description
Returns a list of workflow configuration item values for the workflow
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": (YAML-serialized string) the current value of the configuration item on this level
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "is_templated_string": True if the value is a templated string that can be later expanded

POST /api/v8/workflows/{id_or_name}/config?action=yaml

Description
Creates the value for the given step configuration items on the workflow level using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: the name of the configuration item
  • value: (YAML-serialized string) the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the workflow configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

/api/v8/workflows/{id_or_name}/config/{name}

This REST URI path provides actions and information related to a particular Qorus. Prefix can be passed within the config item name or as following: /v3/workflows/{id_or_name}/config/{name}?prefix={prefix}. workflow configuration item

DELETE /api/v8/workflows/{id_or_name}/config/{name}

Description
Permanently deletes the current value for the configuration item on this workflow level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/workflows/{id_or_name}/config/{name}

Description
Returns a hash for the current workflow configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

PUT /api/v8/workflows/{id_or_name}/config/{name}

Description
Sets the value for the given workflow configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the workflow configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

PUT /api/v8/workflows/{id_or_name}/config/{name}?action=yaml

Description
Sets the value for the given workflow configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: (YAML-serialized string) the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the workflow configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

GET /api/v8/workflows/{id_or_name}/config/{name}?action=yaml

Description
Returns a hash for the current workflow configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "is_set": True if the value is set otherwise False
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "is_templated_string": True if the value is a templated string that can be later expanded
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

DELETE /api/v8/workflows/{id_or_name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on this workflow level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/workflows/{id_or_name}/errors

This REST URI path provides actions and information about workflow order data instance errors for a particular workflow.

GET /api/v8/workflows/{id_or_name}/errors

Description
Returns a list of information of workflow-specific workflow errors for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
Return Value
If neither list nor short are used, then this API returns a list of REST Workflow Error Description Hash elements for the workflow errors for the current workflow corresponding to the arguments

POST /api/v8/workflows/{id_or_name}/errors

Description
Creates a workflow-specific workflow error for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "CREATED-GLOBAL": a new global error was created (only possible if forceworkflow is omitted or False)
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
  • 409 Conflict: ERROR-EXISTS: this exception is thrown if the workflow-specific error definition already exists
Note

POST /api/v8/workflows/{id_or_name}/errors?action=createOrUpdate

Description
Creates or updates a workflow-specific workflow error for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • business_flag: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the new description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • retry_delay_secs: (optional int) an optional retry value in seconds (only accepted if status is set to OMQ::StatRetry)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • status: (optional string) must be one of the following values:
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

/api/v8/workflows/{id_or_name}/errors/{error}

This URI path provides actions and information related to a workflow-specific workflow error

DELETE /api/v8/workflows/{id_or_name}/errors/{error}

Description
Permanently deletes the current workflow error
Return Value
This API returns "OK" upon successful execution
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL

GET /api/v8/workflows/{id_or_name}/errors/{error}

Description
Returns a hash of information about the current workflow error
Return Value
Returns a REST Workflow Error Description Hash (REST API v1 and v2)

PUT /api/v8/workflows/{id_or_name}/errors/{error}

Description
Updates the current workflow-specific workflow error with the new definition given as arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • description: (string) the new description of the error
  • severity: (string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • retry_flag: (bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • business_flag: (bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • retry_delay_secs: (optional int) an optional retry value in seconds (only used if retry_flag is also True)
Return Value
This API returns a string giving the result of the operation; one of:
  • "UPDATED-WORKFLOW": the existing workflow-specific error was updated
  • "CREATED-WORKFLOW": a new workflow-specific error definition was created (only possible in case of a race condition where the current error was deleted during this request)
  • "UNCHANGED-WORKFLOW": the new workflow-specific definition is identical to the old definition
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ERROR_CONTROL
See also

PUT /api/v8/workflows/{id_or_name}/errors/{error}?action=update

Description
Updates the current workflow-specific workflow error with the new definition given as arguments
See also
This API is equivalent to PUT /api/errors/workflow/{id_or_name}/{error}; see that documentation for details.

/api/v8/workflows/{id_or_name}/instances

This REST URI path provides actions and information about workflow execution instances for a particular workflow.

GET /api/v8/workflows/{id_or_name}/instances

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash v3 for the current workflow, plus the following keys:
  • alerts: a list of alerts raised against the workflow; each list element is a REST Alert Hash (may be empty)
  • log_url: a complete URL to the websocket source for the workflow log

/api/v8/workflows/{id_or_name}/orders

This REST URI path provides actions and information about workflow orders for the current workflow.

GET /api/v8/workflows/{id_or_name}/orders

Description
Returns a list of hashes for orders for the current workflow matching the search criteria
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: an alternate key for modified
  • desc: return in descending order
  • ids: an alternate key for workflow_instanceid
  • keyname: the name of a search key to be used with the keyvalue value(s)
  • keyvalue: the value(s) of workflow order search key(s) to use (optionally used in conjunction with keyname)
  • limit: max number of rows to return, if not given, then the value of the "row-limit" option is used (default: 100)
  • maxmodified: maximum modified date
  • maxstarted: maximum start date
  • minstarted: minimum start date
  • modified: minimum modified date
  • offset: row offset
  • sort: columns for sorting the results
  • status: status value(s) (see Workflow, Segment, and Step Status Descriptions for possible values)
  • statuses: an alternate key for status
  • workflow_instanceid: workflow_instanceid values(s)
Return Value
This API returns NOTHING if no orders match or a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow order instance ID
  • workflowid: the workflow ID
  • workflowstatus: the status of the workflow order instance (see Workflow, Segment, and Step Status Descriptions for possible values)
  • status_sessionid: the application session ID that owns the workflow order instance data or 0 if the data is now owned by any application session
  • started: the start date/time of the workflow order instance
  • completed: the completed date/time for the workflow order instance
  • modified: the last modified date/time of the workflow order instance
  • parent_workflow_instanceid: the parent workflow order ID if present
  • synchronous: if 1, indicates that the order is being executed synchronously
  • business_error: a boolean flag indicating if the workflow order has an error status due to a business error
  • operator_lock: a string giving the username of the user with an operator lock on the order
  • note_count: the number of notes stored against the order
  • warning_count: the number of warnings raised against the order
  • error_count: the number of errors raised against the order
  • retry_count: the number of times the order was subject to a RETRY status due to a technical error
  • custom_status: a custom status for the order
  • priority: the priority of the workflow order
  • scheduled: the future scheduled date of the workflow order (if any)
  • custom_status_desc: a description for the custom status (if any)
  • actions: a list of possible actions on the workflow

GET /api/v8/workflows/{id_or_name}/orders?action=listErrors

Description
Returns information about workflow order errors corresponding to the search arguments for the current workflow
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • workflow_instanceid: limit the search to one or more workflow_instanceids
  • error_instanceid: mit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • workflowid: limit the search to one or more workflowids
  • workflowstatus: limit the search to workflow instances with the given status value(s) (see Workflow, Segment, and Step Status Descriptions for possible values)
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

GET /api/v8/workflows/{id_or_name}/orders?action=overview

Description
Returns aggregate order status information for the current workflow.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: optional (parsed as a date); the past cutoff date for the search; only orders with a modified date equal or after this date will be considered; if not present, then defaults to the last 24 hours
  • sqlcache: optional (parsed with Qore::parse_boolean()); if False then no SQL cache will be used for historical info; default True
Return Value
This API returns a hash keyed by order status (see Workflow, Segment, and Step Status Descriptions for possible values) where the values are order counts for the time period in question. One additional hash key is also provided as follows:
  • TOTAL: the total number of orders matched

GET /api/v8/workflows/{id_or_name}/orders?action=processingSummary

Description
Returns information about workflow processing for the current workflow.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • mindate: (required) minimum date
  • maxdate: maximum date
  • seconds: if True then the performance values will be returned as arbitrary-precision numeric values representing seconds, otherwise they will be returned as relative date/time values
  • global: if True then all workflows will be combined into an overall processing report, if False then each workflow gets a separate line in the output
  • grouping: (optional) possible values for reporting performance statistics:
    • "hourly": hourly grouping
    • "daily": daily grouping
    • "monthly": monthly grouping
    • "yearly": yearly grouping
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • workflowid: the workflow ID
  • name: the workflow name
  • version: the workflow version
  • count: the number of workflow orders in the period
  • minstarted: the minimum workflow order start date
  • maxcompleted: the maximum workflow order completion date (if any)
  • minduration: the minimum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • avgduration: the average total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • maxduration: the maximum total elapsed order processing time for workflow orders in the period (starting from workflow order creation)
  • minprocessing: the minimum order processing time for workflow orders in the period (starting from when then order was first processed)
  • avgprocessing: the average order processing time for workflow orders in the period (starting from when then order was first processed)
  • maxprocessing: the maximum order processing time for workflow orders in the period (starting from when then order was first processed)
Errors
  • 409 Conflict: ARGUMENT-ERROR: missing mindate

/api/v8/workflows/{id_or_name}/orders/{id}

This REST URI path provides actions and information about a particular workflow order of a given workflow type

GET /api/v8/workflows/{id_or_name}/orders/{id}

Description
Returns a hash of information about the current workflow order data instance.
Return Value
This API returns a hash with the following keys:
  • name: the name of the workflow
  • version: the version of the workflow
  • author: the author of the workflow
  • workflow_instanceid: the workflow order instance ID
  • workflowid: the ID of the workflow
  • workflowstatus: the status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
  • status_sessionid: the ID of the Qorus application session managing the workflow order data or 0 if none
  • parent_workflow_instanceid: the workflow order instance ID of the parent order for this workflow or NULL if none
  • subworkflow: if 1, indicates that the parent_workflow_instanceid is the parent workflow order in a subworkflow relationship
  • synchronous: if 1, indicates that the order is being executed synchronously
  • errors: the number of errors raised against the order
  • business_error: a boolean flag indicating if the workflow order has an error status due to a business error
  • workflowstatus_orig: if the order status is OMQ::StatBlocked or OMQ::StatCanceled, this value will reflect the original status of the workflow order (see Workflow, Segment, and Step Status Descriptions for possible values)
  • custom_status: a custom status for the order
  • scheduled: the scheduled date
  • priority: the priority of the workflow order
  • started: the date/time the order was created
  • completed: the date/time order processing completed
  • modified: the last modified date/time for the order
  • operator_lock: a string giving the username of the user with an operator lock on the order
  • note_count: the number of notes stored against the order
  • deprecated: a boolean value indicating if the workflow is deprecated or not; deprecated workflows are by default not displayed in the UI
  • autostart: the integer autostart value for the workflow
  • manual_autostart: a boolean flag set if the autostart value has been changed manually, in which case the manual setting takes precendence over any new definitions loaded with oload
  • max_instances: a value limiting the maximum number of execution instances that can run at once
  • external_order_instanceid: a unique external key for the order
  • staticdata: a hash of workflow order static data
  • dynamicdata: a hash of workflow order dynamic data (if any)
  • keys: a hash of workflow order keys and values
  • warning_count: the number of warnings raised against the order
  • error_count: the number of errors raised against the order
  • StepInstances: a list of step hashes giving information about the execution status of workflow steps; each element is a hash with the following keys:
    • workflow_instanceid:
    • stepid: the ID of the step
    • ind: the step array index starting with 0
    • stepname: the name of the step
    • stepversion: the version of the step
    • steptype: type of the step
    • stepstatus: the current execution status of the step (see Workflow, Segment, and Step Status Descriptions for possible values)
    • retries: the number of retries executed on the step
    • skip: a boolean value indicating if the step logic was skipped
    • custom_status: a custom status for the step
    • started: the date/time the step was first executed
    • completed: the date/time step processing completed
    • function_instanceid: the function ID of the primary step function
    • subworkflow_instanceid: the workflow order ID of any subworkflow order instance (for bound subworkflow steps only)
    • business_error: a boolean flag indicating if the step has an error status due to a business error
  • ErrorInstances: a list of hashes giving information about errors and warnings raised against the order; each element is a hash with the following keys:
    • error_instanceid: a unique ID for the error
    • workflow_instanceid: the workflow order instance ID
    • stepid: the stepid where the error was raised
    • ind: the step array index starting with 0 where the error was raised
    • severity: the severity of the error (see Error Severity Codes for possible values)
    • retry: 1 if the error caused a retry
    • error: the string error code for the error
    • description: an optional description of the error
    • info: an optional string providing additional information about the error
    • business_error: a boolean flag indicating if the error is a business error
    • created: the date/time the error was created
  • HierarchyInfo: a hash of workflow order information; the keys are workflow order instance IDs for all workflow orders linked to each other through parent-child relationships in the hierarchy of the current workflow order; the values are order information hashes similar to the top-level of the return value of this API
  • AuditEvents: a list of audit information hashes
  • LastModified: the last modified date/time of the workflow order
  • actions: a list of possible actions on the workflow
  • notes: a list of notes saved against the order; each element is a REST Order Note Hash

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=block

Description
Blocks the current workflow order data instance by changing its status to BLOCKED. An exception will be thrown if the status is IN-PROGRESS. No further processing can be done on workflow order data instances with a CANCELED status (unless the workflow order instance is recovered back from CANCELED to its original status or the status is first updated to ERROR and then to RETRY). Note that CANCELED and BLOCKED statuses have the same effect, however CANCELED is meant to be a permanent or final status, while BLOCKED is meant to be temporary.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=breakLock

Description
Breaks the current workflow order lock so that it can be updated by any authorized user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (required) a string note that gives the reason for breaking the operator lock
Return Value
This API returns "OK" upon successful execution
Note
See also

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=cancel

Description
Blocks the current workflow order data instance by changing its status to CANCELED. An exception will be thrown if the status is IN-PROGRESS. No further processing can be done on workflow order data instances with a CANCELED status (unless the workflow order instance is recovered back from CANCELED to its original status or the status is first updated to ERROR and then to RETRY). Note that CANCELED and BLOCKED statuses have the same effect, however CANCELED is meant to be a permanent or final status, while BLOCKED is meant to be temporary.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=dynamicData

Description
Replaces the dynamic data for the current order
Arguments
This API takes the following hash argument:
  • newdata (*hash<auto>): the new dynamic data for the current workflow order
Return Value
This API returns a value of type string: OK
Errors
  • 400 Bad Request: invalid or missing argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

POST /api/v8/workflows/{id_or_name}/orders/{id}?action=execSynchronous

Description
Executes a workflow in synchronous mode against the current order, which must have status OMQ::StatReady or OMQ::StatScheduled; it is not possible to process workflow data with other statuses synchronously.
The call will normally return only after the workflow reaches a OMQ::StatComplete or OMQ::StatError state, unless the system or the workflow order data instance are manually stopped while the workflow order data instance is being processed, in which case other statuses can be returned.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • options: (hash) an optional hash of option names and values; if any options are not valid for the workflow, then an exception is raised and the synchronous workflow execution instance is not started
Return Value
This API returns a hash with the following keys:
  • workflow_instanceid: the workflow instance ID of the order
  • status: the status of the workflow
  • dynamicdata: the dynamic data of the workflow order instance
Errors
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: cannot start new workflows because the system is shutting down
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires at least one of the following permissions: OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_EXEC_SYNC_WORKFLOW
See also

GET /api/v8/workflows/{id_or_name}/orders/{id}?action=listErrors

Description
Returns information about workflow order errors for the given workflow order instance
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderby: one or more field names for sorting the output
  • error: the error text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • description: the description text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given)
  • info: the info text to search (can also include '' characters for use with the LIKE operator; in this case only 1 value can be given
  • stepid: limit the search to one or more stepids
  • severity: limit the search to one or more severity values
  • name: limit the search to one or more step names
  • version: limit the search to one or more step versions
  • retry: limit the search to errors with or without the retry flag
  • business_error: limit the search to errors with or without the business_error flag
  • error_instanceid: mit the search to one or more error_instanceids
  • mindate: give the lower date range for the error search
  • maxdate: give the upper date range for the error search
  • limit: the maximum number of errors to return
  • offset: the starting error to return (use when paging for example)
Return Value
This API returns a list of hashes with the following keys for all data matched according to the search arguments:
  • name: the name of the workflow
  • version: the version of the workflow
  • workflow_instanceid: the workflow instance ID
  • workflowid: the workflow ID
  • stepid: the step ID where the error occurred
  • stepname: the name of the step where the error occurred
  • stepversion: the version of the step where the error occurred
  • ind: the array step index number where the error occurred
  • workflowstatus: current status of the workflow (see Workflow, Segment, and Step Status Descriptions for possible values)
  • started: the date and time when the workflow order started processing
  • completed: the date and time when the workflow order was completed
  • parent_workflow_instanceid: any parent workflow instance ID
  • custom_status: the custom status of the workflow order, if any
  • priority: the priority of the workflow order
  • scheduled: any scheduled date for the workflow order
  • error_instanceid: the error instance ID
  • error: the error code string
  • description: a description for the error (if any)
  • info: additional information about the error (if any)
  • severity: an error severity code (see Error Severity Codes for possible values)
  • created: the date and time the error was raised
  • retry: the retry count of the error
  • business_error: a boolean flag indicating of the error is a business error
  • custom_status_desc: a descriptive string for the custom status (if any)

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=lock

Description
Locks the current workflow order so that it can only be updated by the current user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (required) a string note that gives the reason for setting the operator lock
Return Value
This API returns "OK" upon successful execution
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_LOCK_WORKFLOW_ORDER
See also

GET /api/v8/workflows/{id_or_name}/orders/{id}?action=notes

Description
Returns a list of notes saved against the order; each element is a REST Order Note Hash.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • limit: the maximum number of notes to return; if omitted then all notes are returned
Return Value
This API returns a list of hashes of notes saved against the order; each element is a REST Order Note Hash.
Errors
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)

POST /api/v8/workflows/{id_or_name}/orders/{id}?action=notes

Description
Creates an order note on the current workflow order
Arguments
This API takes the following hash argument:
  • note (string): the note to create on the order
Return Value
This API returns a value of type string: OK
Errors
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=reschedule

Description
Sets or removes the scheduled date for the current workflow order data instance. Setting the scheduled date for a workflow order means that the workflow order data will not be processed before the scheduled date and time. The workflow order data must normally have status OMQ::StatReady or OMQ::StatScheduled to be rescheduled, however also workflows with OMQ::StatCanceled and OMQ::StatBlocked statuses can be rescheduled if their original status is OMQ::StatReady or OMQ::StatScheduled.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • date: (optional) parsed as a date; this is the new scheduled date to set; if not present, then any scheduled date will be removed
Return Value
This API returns "OK" upon successful execution
Errors
  • 409 Conflict: SESSION-ERROR: cannot reschedule workflow data owned by a foreign session
  • 409 Conflict: WORKFLOW-STATUS-ERROR: only workflows with status OMQ::StatReady or OMQ::StatScheduled or blocked or canceled workflows with original status OMQ::StatReady or OMQ::StatScheduled can be rescheduled
  • 409 Conflict: RESCHEDULE-ERROR: reschedule failed because workflow order data started processing while the request was being processed
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RESCHEDULE_WORKFLOW_ORDER
See also

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=retry

Description
Retries the current workflow order instance; in order to make a retry; the workflow order status must be OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry.
Return Value
This API returns a hash with the following keys:
  • steps_updated: (deprecated) always 0 in this version of Qorus
  • segments_updated: the number of segments updated
  • workflow_updated: always True in this version of Qorus
  • workflow_status: always OMQ::StatRetry in this version of Qorus
  • cached: True if the workflow data is currently cached
Errors
  • 409 Conflict: STATUS-ERROR: workflow data does not have either OMQ::StatError, OMQ::StatAsyncWaiting, or OMQ::StatRetry status
  • 409 Conflict: SESSION-ERROR: cannot change status for workflow data managed by another Qorus instance (foreign session ID)
  • 409 Conflict: RETRY-ERROR: invalid workflow instance ID
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_RETRY_WORKFLOW_ORDER
See also
omq.system.retry-workflow-instances()

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=setError

Description
Changes the status of a workflow order data instance to OMQ::StatError, as long as the starting status is OMQ::StatRetry, OMQ::StatCanceled, OMQ::StatBlocked, or OMQ::StatAsyncWaiting. If the status is any other status, an exception will be thrown.

To set a workflow order data instance with a OMQ::StatWaiting status to OMQ::StatError, set the child workflows to OMQ::StatError first and the status of the parent workflow order will be updated automatically.

When setting a workflow order from OMQ::StatCanceled to OMQ::StatError, outstanding events will be queued and the associated queued event keys will be present in the return value.
Return Value
This API returns a hash with the following keys:
  • steps_updated: number of steps updated
  • segments_updated: number of segments updated
  • workflow_status: always OMQ::StatError
  • old_status: the old workflow data status
  • queued_detached_segments: number of detached segment events queued
  • queued_subworkflows: number of subworkflow events queued
  • queued_async_messages: number of async events queued
  • queued_sync_events: number of workflow synchronization events queued
  • queued_async_retries: number of async events queued
  • queued_retries: number of retry events queued
  • queued_fixed_retries: number of retry events with a fixed retry time queued
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_WORKFLOW_ORDER_ERROR
See also

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=setPriority

Description
Changes the priority for an existing workflow order data instance. The workflow order data must not have status OMQ::StatComplete.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • priority: the new order priority from 0 - 999; priority 0 is the highest; 999 is the lowest
Return Value
This API returns "OK" upon successful execution
Errors
  • 409 Conflict: SESSION-ERROR: cannot reschedule workflow data owned by a foreign session
  • 409 Conflict: WORKFLOW-STATUS-ERROR workflows with status OMQ::StatComplete cannot have their priority changed
  • 403 Forbidden: AUTHORIZATION-ERROR this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_REPRIORITIZE_WORKFLOW_ORDER
See also

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=skipStep

Description
Skips execution of a step in the current workflow order. Sometimes execution for a given step must be skipped, but the rest of the workflow logic should be executed. This API call allows Qorus to continue executing a workflow order data instance after skipping the given step. Only steps with OMQ::StatError, OMQ::StatRetry, OMQ::StatEventWaiting, or OMQ::StatAsyncWaiting can be skipped. Subworkflow steps with any status cannot be skipped; the child workflow must be corrected instead.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • stepid: (required) the step ID to skip
  • ind: (optional) one or more step array index values to skip (ranges accepted; ex: "1,3,5-7"); if not present defaults to 0
  • noretry: (optional) parsed with Qore::parse_boolean(); if True then no retry will be executed
Errors
  • 409 Conflict: SKIP-STEP-ERROR: step is a subworkflow step; step has not been executed in the given workflow order instance; the given workflow instance ID does not exist
  • 409 Conflict: STEP-STATUS-ERROR: step status does not allow it to be skipped (ex: IN-PROGRESS, COMPLETE)
  • 409 Conflict: SESSION-ERROR: workflow order instance belongs to another Qorus session
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
  • 403 Forbidden: WORKFLOW-ACCESS-ERROR: this is exception is thrown when Role Based Access Control is enabled and the user does not have the right to access the given workflow (for more information, see Interface Groups)
Note

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=staticData

Description
Replaces the static data for the current order
Arguments
This API takes the following hash argument:
  • newdata (hash<auto>): the new static data for the current workflow order; must be a non-empty
Return Value
This API returns a value of type string: OK
Errors
  • 400 Bad Request: invalid or missing argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=unblock

Description
Resets the status of a blocked workflow order data instance to its original status before blocking.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=uncancel

Description
Resets the status of a canceled workflow order data instance to its original status before canceling.
Arguments
Return Value
This API returns a WorkflowOrderStatusInfo hash with the following key (provides status information about the order processed):
  • workflow_status (string): the status of the order after updating
Errors
  • 403 Forbidden: access or authorization error
  • 409 Conflict: exception processing request
Note
Requires one of the following permissions:

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=unlock

Description
Unlocks the current workflow order so that it can be updated by any authorized user.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: (optional) a string note that gives the reason for removing the operator lock; if not passed, a default note will be added
Return Value
This API returns "OK" upon successful execution
Note
See also

PUT /api/v8/workflows/{id_or_name}/orders/{id}?action=updateKeys

Description
Replace all order keys for the current workflow order
Arguments
This API takes the following hash arguments:
  • orderkeys (OrderKeySet): the order keys to replace for the current workflow order
    • key (list<string>): list<string> value
  • truncate (*bool): truncate any key values automatically to the length of the column (4000 characters)
Return Value
This API returns an OrderKeySet hash; keys have the following format:
  • any (list<string>): all order keys for the order after updating
Errors
  • 400 Bad Request: invalid orderkeys argument
  • 403 Forbidden: access or authorization error
Note
Requires one of the following permissions:

/api/v8/workflows/{id_or_name}/staticdata_type

This REST URI path provides information about workflow static data types

GET /api/v8/workflows/{id_or_name}/staticdata_type

Description
Returns data type information
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • soft: optional; parsed with Qore::parse_boolean(); if True then the type is returned with soft types to be used as the target for a mapper

/api/v8/workflows/{id_or_name}/stepinfo

This REST URI path provides information about steps in a workflow.

/api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}

This REST URI path provides information about a particular step in a workflow.

/api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config

This REST URI path provides actions and information related to Qorus step configuration items in the context of a particular workflow

GET /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config

Description
Returns a list of step configuration items for the step in the context of the declaring workflow
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:1") or "global" or "default")
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "is_templated_string": True if the value is a templated string that can be later expanded

GET /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config?action=yaml

Description
Returns a list of step configuration items for the step as a YAML-serialized string
Return Value
This API returns a list of hashes with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (YAML-serialized string) the default value of the configuration item
  • "value": (YAML-serialized string) the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined (each element is a YAML-serialized string)
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:1") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

/api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}

This REST URI path provides actions and information related to a particular Qorus. Prefix can be passed within the config item name or as following: /v3/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}?prefix={prefix}. step configuration item in the context of a particular workflow

DELETE /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}

Description
Permanently deletes the current value for the configuration item on this step level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value: deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}

Description
Returns a hash for the current step configuration item
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": the default value of the configuration item
  • "value": the value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

PUT /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}

Description
Sets the value for the given step configuration item
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value: the value of the configuration item; must be compatible with the item's declared type
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value: the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

PUT /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}?action=yaml

Description
Sets the value for the given step configuration item using a YAML-serialized string
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • value (YAML-serialized string): the value of the configuration item
Return Value
This API returns a hash with the following keys:
  • inserted: True or False (returned if the value has been inserted)
  • updated: True or False (returned if the value has been updated)
  • value (YAML-serialized string): the new value
  • info: info about the service configuration item change action
Errors
  • 400 Bad Request: returned if the request has no value key
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

GET /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}?action=yaml

Description
Returns a hash for the current step configuration item as a serialized YAML string
Return Value
This API returns a hash with the following keys:
  • "name": the name of the configuration item
  • "prefix": the prefix of the configuration item
  • "type": the type of the configuration item
  • "desc": the description of the configuration item
  • "default_value": (serialized YAML string) the default value of the configuration item
  • "value": (serialized YAML string) the current value of the configuration item
  • "strictly_local": if the configuration item is defined strictly on local level
  • "is_set": True if the value is set otherwise False
  • "config_group": the group of the configuration item
  • "allowed_values": (serialized YAML string) the list of allowed values for the configuration item if defined
  • "level": the level from where the value is obtained (interface level (e.g. "step:1", "workflow:2") or "global" or "default")
  • "is_templated_string": True if the value is a templated string that can be later expanded

DELETE /api/v8/workflows/{id_or_name}/stepinfo/{id_or_name}/config/{name}?action=yaml

Description
Permanently deletes the current value for the configuration item on this step level
Return Value
This API returns a hash with the following key:
  • info: a string confirming the delete operation
  • deleted: True if value has been deleted
  • value (YAML-serialized string): deleted value
Errors
  • 403 Forbidden: AUTHORIZATION-ERROR: this exception is thrown when Role Based Access Control is enabled and the user does not have sufficient privileges for the operation
Note

/api/v8/{interface}/{id_or_name}/logger

This URI path provides ability to customize Qorus interface logger configurations

DELETE /api/v8/{interface}/{id_or_name}/logger

Description
Delete logger
Return Value
If success 200 OK, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/{interface}/{id_or_name}/logger

Description
Returns logger info
Return Value
This API returns 200 OK and hash with the following keys:
  • loggerid: (int) logger id
  • params: (hash) logger params
    • level: (hash) LoggerLevel
      • "key": logger level string representation
      • "value": logger level int representation
    • name: (string) logger name
    • additivity: (bool) logger additivity
  • interface_table_name: (string) interface table name (jobs/workflows/services). If set means default logger

POST /api/v8/{interface}/{id_or_name}/logger

Description
Create Logger
Arguments
This API takes the following argument as URI arguments:
  • level: required; (int|string) LoggerLevel
  • name: (string) logger name
  • additivity: (bool) logger additivity (default True)
  • cloneDefault: (bool) create logger with appenders based on default logger
Return Value
If success 200 with the logger ID created, in case of failure 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/{interface}/{id_or_name}/logger

Description
Set logger params
Arguments
This API takes the following argument as URI arguments:
  • level: (int|string) LoggerLevel
  • name: logger name to set
  • additivity: logger additivity to set
Return Value
If success 200 OK, in case of fail 400 and string with error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL

/api/v8/{interface}/{id_or_name}/logger/appenders

This URI path provides ability to customize Qorus inerface logger appenders

DELETE /api/v8/{interface}/{id_or_name}/logger/appenders

Description
Delete logger appender with obtained id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be deleted
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_DELETE_LOGGER or OMQ::QR_LOGGER_CONTROL

GET /api/v8/{interface}/{id_or_name}/logger/appenders

Description
Return all logger appenders
Return Value
This API returns 200 OK and list with the following hashes:
  • appenderId: (int) appenderId
  • params: (hash) possible appender parameters, might be missing if not set
    • name: (string) appender name
    • layoutPattern: (string) appender layout pattern
    • rotation: (int) appender layout pattern
    • filename: (string) appender filename

POST /api/v8/{interface}/{id_or_name}/logger/appenders

Description
Create logger appenders
Arguments
This API takes the following argument as URI arguments:
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK and appender id, in case of fail one of the error codes: 400, 409 and string of error description
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
  • 409 Conflict: conflict with the current state
Note
requires permission OMQ::QR_CREATE_LOGGER or OMQ::QR_LOGGER_CONTROL

PUT /api/v8/{interface}/{id_or_name}/logger/appenders

Description
Update logger appender with the given id
Arguments
This API takes the following argument as URI arguments:
  • id: required; (int); id of the appender to be update
  • name: (string) the name of the appender
  • layoutPattern: (string) the layout for the appender
  • filename: (string) the output filename
  • encoding: (string) the file's output encoding
  • appenderType: required; (string) appender type, case sensitive (see Logger for possible values) (ex. LoggerAppenderFileRotate, LoggerAppenderFile, LoggerAppenderStdOut ...)
  • rotationCount: (int) the number of files in rotation chain, if count is <=0 then no ratation is performed. Only for rotation appenders
  • archivePattern: (string) pattern to evaluate archive filename
Return Value
If success 200 OK, in case of fail 400 and string with error description
Note
requires permission OMQ::QR_MODIFY_LOGGER or OMQ::QR_LOGGER_CONTROL