Qorus Integration Engine®  5.1.19_git
Qorus REST API v1

Table of Contents

/api/api/metrics

This REST URI path provides qorus metrics

GET /api/api/metrics

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

/api/async-queues

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

GET /api/async-queues

Description
Returns a hash of information about the asynchronous queue
Return Value
This API returns a hash with the following keys:
  • queueid: the queue ID
  • name: the queue name

/api/classes

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

GET /api/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):
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

GET /api/classes?action=list

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

/api/classes/{id_or_name}

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

GET /api/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

/api/constants

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

GET /api/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

/api/constants/{id_or_name}

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

GET /api/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

/api/debug

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

/api/debug/development

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

/api/debug/interface-serialization

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

/api/debug/order-stats

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

/api/debug/order-stats-summary

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

/api/debug/sync-cache

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

/api/debug/sync-summary

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

/api/debug/threads

This REST URI path provides information related to Qorus threads

GET /api/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/debug/threads/{tid}

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

GET /api/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/debug/workflow-control

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

/api/errors

This URI path provides actions and information related to workflow errors

GET /api/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 (REST API v1 and v2) elements corresponding to the arguments

POST /api/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 description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional) 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • 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/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 description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional) 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
  • 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/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/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 (REST API v1 and v2) elements corresponding to the arguments

/api/errors/global

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

GET /api/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 (REST API v1 and v2) elements for the global workflow errors corresponding to the arguments

POST /api/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 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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/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: (optional bool) parsed with Qore::parse_boolean(); a boolean business flag value (if not present then False is assumed)
  • description: (required string) the 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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/errors/global/{error}

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

DELETE /api/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/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/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):
  • 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-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/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/errors/workflow

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

GET /api/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 (REST API v1 and v2) elements for the workflow errors for the current workflow corresponding to the arguments

/api/errors/workflow/{id_or_name}

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

GET /api/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 (REST API v1 and v2) elements for the workflow errors for the current workflow corresponding to the arguments

POST /api/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 description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional) 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
  • retry_delay_secs: (optional int) an optional retry value in seconds (only used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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
  • 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 forceworkflow option as described above

POST /api/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 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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 (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)
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 forceworkflow option as described above

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

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

DELETE /api/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/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 (REST API v1 and v2)

PUT /api/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):
  • 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/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/errors/workflow/{id_or_name}/{error}; see that documentation for details.

/api/errors/{error}

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

DELETE /api/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/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/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):
  • 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 accepted 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
  • "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/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/exec

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

GET /api/exec

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash, 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/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/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/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/exec/{id}

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

GET /api/exec/{id}

Return Value
This API returns a hash with the keys of REST Execution Instance Hash, 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/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/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/exec/{workflowname}

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

GET /api/exec/{workflowname}

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash, 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/exec/{workflowname}?action=desc

Return Value
Returns a string describing the workflow.

PUT /api/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/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/functions

This REST API path provides actions and information about Qorus functions

GET /api/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

GET /api/functions?action=list

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

/api/functions/{id_or_name}

This REST API path provides actions and information about specific functions

GET /api/functions/{id_or_name}

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

/api/groups

This URI path provides actions and information related to interface groups

DELETE /api/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/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/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
  • 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: GROUP-ERROR: missing group or desc arguments
Note
requires permission OMQ::QR_GROUP_CONTROL or OMQ::QR_ADD_GROUP
See also

GET /api/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/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/groups/{name}

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

DELETE /api/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/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/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

PUT /api/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/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/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/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/jobresults

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

GET /api/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/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/jobresults/{id}

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

GET /api/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/jobs

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

GET /api/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: options; either "active" or "inactive" to filter jobs based on their active status
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

PUT /api/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/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/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/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/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/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.

GET /api/jobs/{id_or_name}

Description
Returns a hash of job information
Return Value
Returns a REST Job Description Hash for the current job, plus the following key:
  • state: a hash of job state data (if any)
Errors
  • 403 Forbidden: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)

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

Description
Disables the current job.
Return Value
This API returns a hash with the following keys:
  • name: the job name
  • version: the job version
  • jobid: the job ID
  • info: info about the job 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: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
Note

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

Description
Enables the current job if it is disabled.
Return Value
This API returns a hash with the following keys:
  • name: the job name
  • version: the job version
  • jobid: the job ID
  • info: info about the job 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: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
Note

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

Description
Reloads a job from the database; if it 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.
Return Value
This API returns a descriptive string; ex: started jobid 7 "myjob1" after 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: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
  • 409 Conflict: API-CALL-ERROR: cannot reset a disabled job
Note
requires permission OMQ::QR_JOB_CONTROL or OMQ::QR_RESET_JOB
See also
omq.system.job.reset()

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

Description
Runs a job and returns the results of job execution
Return Value
This API returns a hash with the following keys:
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 or OMQ::QR_RUN_JOB
See also
omq.system.job.run()

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

Description
Updates the schedule for the current job from the arguments. 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 (either as URI arguments or in the message body):
  • schedule: 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: 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 hash with the following keys:
  • jobid: the job ID
  • name: the job name
  • [schedule]: (if used as the argument) the new job schedule
  • [duration]: (if used as the argument) the new job duration
  • info: a string giving a description of 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
  • 403 Forbidden: JOB-ACCESS-ERROR: the user does not have the right to access the given job (for more information, see Interface Groups)
  • 409 Conflict: JOB-SCHEDULE-ERROR: neither schedule nor duration parameters given
  • 409 Conflict: CRON-ERROR: cron schedule cannot be parsed or 0 second (or non-integer) duration given
Note
requires permission OMQ::QR_JOB_CONTROL, OMQ::QR_RESCHEDULE_JOB, or OMQ::QR_CREATOR_CONTROL
See also
omq.system.job.schedule()

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

Description
Updates the "active" status 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.

Updating a job to active will start the job immediately unless the expiry date is past or the job is a member of a disabled group. Changing a currently-active job to inactive will stop the job immediately
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 keys:
  • jobid: the job ID
  • name: the job name
  • active: the new active state of the job
  • info: a descriptive string; ex: jobid 7 "myjob1" is already active and running
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)
  • 409 Conflict: JOB-ERROR: cannot set expired jobs to active
See also
omq.system.job.set-active()

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

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

PUT /api/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 arguments (either as URI arguments or in the message body):
  • date: (optional) parsed as a date; the expiry date of the job; if not present any expiry date will be removed
Return Value
This API returns a hash with the following keys:
  • jobid: the job ID
  • name: the job name
  • expiry_date: the new expiry date for the job
  • info: a descriptive string; ex: jobid 7 "myjob1", expiry date: null, updated expiry date for running 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
  • 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, OMQ::QR_MODIFY_JOB_EXPIRY, or OMQ::QR_CREATOR_CONTROL
See also
omq.system.job.set-expiry()

PUT /api/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/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

/api/jobs/{id_or_name}/results

This REST API path provides actions and information related to the results of specific jobs.

GET /api/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/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/logout

This REST API path provides the logout action

POST /api/logout

Description
Removes the token of the current session.
Arguments
None
Return Value
None

/api/logs

This REST URI path provides actions and information related to Qorus system logs and websocket log sources

GET /api/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/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/mappers

This URI path provides actions and information related to system mappers

GET /api/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

PUT /api/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/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/mappers/{id_or_name}

This URI path provides actions and information related to a specific system mapper

GET /api/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/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/mappertypes

This REST URI path provides actions and information related to all mapper types

See also
qorus.mapper-modules

GET /api/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/mappertypes/{name}

This REST URI path provides actions and information related to a specific mapper type

See also
qorus.mapper-modules

GET /api/mappertypes/{name}

Description
Returns a hash describing the current system mapper type
Return Value
This API returns a REST Mapper Type Description Hash

/api/orders

This URI path provides information and actions related to workflow order data.

GET /api/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/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/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 th e 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/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/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

PUT /api/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

PUT /api/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/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/orders/{id}

This REST URI path provides actions and information about specific workflow orders.

GET /api/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 booelan 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/orders/{id}?action=block

Description
Blocks the current workflow order data instance by changing the status to OMQ::StatBlocked. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatBlocked status (unless the workflow instance is recovered back from OMQ::StatBlocked or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Return Value
This API returns a hash with the following keys:
  • workflow_status: the status of the workflow order
Errors
  • 409 Conflict: BLOCK-WORKFLOW-ERROR: invalid status, foreign session id, missing original status, unblock operation already in progress
  • 403 Forbidden: 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_BLOCK_WORKFLOW_ORDER
See also

PUT /api/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/orders/{id}?action=cancel

Description
Cancels the current workflow order data instance by changing its status to OMQ::StatCanceled. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatCanceled status (unless the workflow instance is recovered back from OMQ::StatCanceled or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Return Value
This API returns a hash with the following keys:
  • 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: 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_CANCEL_WORKFLOW_ORDER
See also

PUT /api/orders/{id}?action=dynamicData

Description
Replaces the dynamic data for an existing order.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (hash) the new dynamic data for the current workflow order; can also be 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
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

POST /api/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/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/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/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/orders/{id}?action=notes

Description
Creates an order note on the current workflow order.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • note: the note to create on 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
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_ORDER_INFO

PUT /api/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/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/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/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/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/orders/{id}?action=staticData

Description
Replaces the static data for an existing order.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: the new static data for the current workflow order; must be 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: ORDER-STATIC-DATA-ERROR: the new static data hash cannot be empty
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

PUT /api/orders/{id}?action=unblock

Description
Resets the status of a blocked workflow order data instance to its original status before blocking.
Return Value
This API returns a hash with the following keys:
  • workflow_status: the status of the workflow order
Errors
  • 409 Conflict: BLOCK-WORKFLOW-ERROR: invalid status, foreign session id, missing original status, unblock operation already in progress
  • 403 Forbidden: 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_BLOCK_WORKFLOW_ORDER
See also

PUT /api/orders/{id}?action=uncancel

Description
Resets the status of a canceled workflow order data instance to its original status before canceling.
Return Value
This API returns a hash with the following keys:
  • 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: 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_CANCEL_WORKFLOW_ORDER
See also

PUT /api/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/orders/{id}?action=updateKeys

Description
Sets order keys for the current workflow order; any keys given here will replace existing order keys.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderkeys: (hash) the order keys to replace for the current workflow order
Return Value
This API returns a hash of all order keys for the order after updating
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: ORDER-KEYS-ERROR: the orderkeys argument was missing or not a hash
  • 409 Conflict: INVALID-WORKFLOW-KEY: an order key was given that is not valid for the workflow
  • 409 Conflict: DUPLICATE-KEY-VALUE: the same value may not appear more than once for any given key
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ORDER_CONTROL

/api/perms

This REST URI path provides actions and information related to RBAC permissions

GET /api/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/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/perms/{perm}

This REST URI path provides actions and information related to a specific RBAC permission

DELETE /api/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/perms/{perm}

Description
Returns information about the current permission
Return Value
Returns a REST Permission Hash for the current permission

PUT /api/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/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/public/info

This URI path implements token-based user authentication.

GET /api/public/info

Description
Returns system information that is publicly available (without authentication).
Arguments
None
Return Value
This API returns a hash with the following keys:
  • instance-key: Qorus instance identifier
  • omq-version: Qorus executable version
  • omq-build: Qorus executable git hash
  • qore-version: Qore library version
  • omq-schema: Qorus system schema info
Since
Qorus 3.1.0.p10 includes the omq-schema key

/api/public/login

This URI path implements token-based user authentication.

POST /api/public/login

Description
Takes the user's credentials as arguments and returns the token for token-based authentication.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • user: the username
  • pass: the user's password
Remarks
Currently the username and password are sent in plain text format. Please consider using HTTPS instead of HTTP to protect the users' privacy.
Return Value
This API returns a hash with the following key:
  • token: the token to be used for the session

/api/releases

This REST URI path provides actions and information about Qorus releases

GET /api/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/releases/{release}

This REST URI path provides actions and information about a specific Qorus release

GET /api/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/remote

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

GET /api/remote

Description
Returns a list of child URI path components
Return Value
Returns a list of child URI path components as follows:

GET /api/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/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/remote/datasources

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

GET /api/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/remote/datasources

Description
Creates a new datasource connection in memory
Arguments
This API takes a hash argument (either as URI arguments or in the message body) with the keys of a Datasource Hash, plus the following key:
  • name: (required) the name of the new datasource
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_DATASOURCE_CONTROL or OMQ::QR_ADD_DATASOURCE

PUT /api/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/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/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/remote/datasources/{name}

This REST URI path provides actions and information related to a specific Qorus system datasource

DELETE /api/remote/datasources/{name}

Description
Deletes the given datasource from the server's internal cache
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: DATASOURCE-ERROR: this exception is thrown if the given datasource does not exist or is a system datasource
Note

GET /api/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/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) with the keys of a Datasource Hash
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: DATASOURCE-ERROR: this exception is thrown if the call tries to modify a locked system datasource or invalid options are passed
Note
See also

PUT /api/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
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/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/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/remote/qorus

This REST URI path provides actions and information related to Qorus remote connections

GET /api/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

GET /api/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/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/remote/qorus/{name}

This REST URI path provides actions and information related to a specific remote connection

GET /api/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/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
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/remote/user

This REST URI path provides actions and information related to Qorus user connections

GET /api/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 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/remote/user

Description
Creates a new user connection from the arguments supplied
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • name: (required string) the name of the user connection
  • desc: (required string) the description for the new user connection
  • url: (required string) the URL for the new user connection
  • options: (optional hash) a hash of options for the user connection (also "opts" is accepted as an alias for "options")
Return Value
This API returns a hash with the following key:
  • info: a string confirming the user connection creation
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: missing or invalid name, desc, url, or options arguments
  • 409 Conflict: CONNECTION-ERROR: connection already exists; unknown scheme in URL
Note
requires permission OMQ::QR_USER_CONNECTION_CONTROL or OMQ::QR_ADD_USER_CONNECTION
See also

GET /api/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/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/remote/user/{name}

This REST URI path provides actions and information related to a specific user connection

DELETE /api/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/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
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/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

PUT /api/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
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/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/roles

This REST URI path provides actions and information related to Qorus roles

GET /api/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/roles

Description
Permanently add a new role to the system
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • role: (required) the name of the role to add
  • desc: (required) the description of the role
  • perms: (optional) a comma-separated string will be split into a list; a single permission or a list of permissions to add to the role; note that users must have at least the OMQ::QR_LOGIN permission to connect to the server
  • groups: (optional) a comma-separated string will be split into a list; a single group or a list of groups to add to the role
Return Value
This API returns a hash with the following key:
  • info: a string describing the role clone 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
  • 409 Conflict: ROLE-ERROR: missing or invalid role or desc arguments
  • 409 Conflict: RBAC-ADD-ROLE-ERROR: invalid role (role already exists)
Note
See also

GET /api/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/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/roles/{role}

Description
Deletes the current role
Return Value
This API returns a hash with the following key:
  • info: a string describing the role 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_ROLE
See also

GET /api/roles/{role}

Description
Returns a hash describing the current role
Return Value
This API returns a REST Role 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_USER_CONTROL

PUT /api/roles/{role}

Description
Modifies the current role
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • desc: (string) role description
  • perms: (list of strings) a comma-separated string will be split into a list; the new list will replace the current list unless the permission names are preceded by "+" or "-", meaning add or remove a permission, respectively (in which case all permissions must be preceded by a "+" or "-")
  • groups: (list of strings) a comma-separated string will be split into a list; the new list will replace the current list unless the group names are preceded by "+" or "-", meaning add or remove a group, respectively (in which case all group names must be preceded by a "+" or "-")
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-ROLE-ERROR: no valid keys in hash, invalid permission, invalid group
Return Value
Returns a hash of the role attributes updated
Note
See also

POST /api/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 (either as URI arguments or in the message body):
  • target: (required) the name of the new cloned role
  • desc: (required) the description of the new cloned role
Return Value
This API returns a hash with the following key:
  • info: a string describing the role clone 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
  • 409 Conflict: ROLE-ERROR: missing or invalid target or desc arguments
  • 409 Conflict: RBAC-ADD-ROLE-ERROR: invalid role (target already exists)
Note
requires permission OMQ::QR_USER_CONTROL or OMQ::QR_ADD_ROLE
See also

PUT /api/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/services

This REST URI path provides actions and information related to Qorus services.

GET /api/services

Description
Returns a list of service hashes according to the arguments passed.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • status: 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
  • list: optional; parsed with Qore::parse_boolean(); if True then a list of service names is returned
  • short: optional; parsed with Qore::parse_boolean(); if True then a list of short strings with service names and descriptions is returned
Return Value
If neither list nor short are used, then a list of hashes is returned, one element for each accessible service (depending on the calling users accessible interface groups); each hash in the returned has the following keys:
  • type: the type of the service; one of:
    • "system": for system services
    • "user": for user services
  • name: the service name
  • version: the service version
  • patch: the service patch string (if any)
  • desc: the service description
  • author: the author of the service (if any)
  • serviceid: the service ID
  • parse_options: a list of symbolic parse options for the service program container (if any)
  • 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
  • log: the complete path to the service log file
  • threads: the number of active threads in the service
  • autostart: boolean value indicating if the service should be autostarted or not
  • manual_autostart: booelan 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
  • loaded: date/time the service was loaded
  • methods: a list of hashes for each service method; each hash element has the following keys:
    • name: the name of the method
    • desc: a description of the method
  • resources: a REST Service Resource Hash (if any)
  • resource_files: a list of hashes giving service resource file information (if any); each list element has the following keys:
    • type: the type code for the service resource
    • name: the name of the service resource
  • options: a hash of options set on the service
  • groups: a list of interface groups that the service belongs to; each list element is a REST Interface Group Hash (may be empty)
  • alerts: a list of alerts raised against the service; each list element is a REST Alert Hash (may be empty)
  • lib: a REST Library Object Hash
  • log_url: a complete URL to the websocket source for the service log
  • enabled: a boolean flag indicating if the service is enabled or not; disabled services cannot be loaded
  • connections: a list of connection objects that this service depends on; each list element is a REST Connection Dependency Hash (may be empty)

PUT /api/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/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/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/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 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/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/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/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/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/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/services/{id_or_name}

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/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:
  • 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
  • description: the description of the service (if any)
  • author: the author of the service (if any)
  • parse_options: a list of symbolic parse options for the service program container
  • autostart: a boolean value indicating if the service should be autostarted or not
  • manual_autostart: a booelan 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
  • enabled: a boolean flag indicating if the service is enabled or not; disabled services cannot be loaded
  • created: the date/time the service was created
  • modified: the date/time the service was last modified
  • mappers: a list of mappers associated with the service (can be NOTHING); each mapper element is a REST Mapper Hash
  • vmaps: a list of value maps associated with the service (can be NOTHING); each value map element is a REST Value Map Hash
  • latest: a boolean flag indicating if the current contextual service is the latest service of its type and name
  • methods: a list of REST Service Method Hash elements
  • groups: a list of interface groups that the service belongs to; each list element is a REST Interface Group Hash (may be empty)
  • 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
  • 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
  • threads: the number of threads running in the service
  • resources: a REST Service Resource Hash
  • log_url: a complete URL to the websocket source for the service log
  • options: a hash of options set on the service
  • connections: a list of connection objects that this service depends on; each list element is a REST Connection Dependency Hash (may be empty)
  • alerts: a list of alerts raised against the service; each list element is a REST Alert Hash (may be empty)
  • state: a hash of saved service state data (if any); see ServiceApi::saveStateData() for more info

PUT /api/services/{id_or_name}

Description
Performs a single update of the service and returns the value for that update.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body): Note that if multiple arguments are passed, only the first recognized argument is processed in the order listed above.
Return Value
This API returns return values depending on the arguments; see the links above for more information
Errors
  • 400 Bad Request: invalid or missing arguments to REST call
Note
permissions are required depending on the arugments used; see links in the argument section for more information

PUT /api/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/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

PUT /api/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

PUT /api/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

PUT /api/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/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/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/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

PUT /api/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/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/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.

GET /api/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/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.

POST /api/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/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/services/{id_or_name}/resource_files

This REST URI path provides information about service resource files.

GET /api/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/services/{id_or_name}/resource_files/{name}

This REST URI path provides information about a particular service resource file.

GET /api/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

/api/services/{id_or_name}/{method}

This REST path provides actions and information about service methods

GET /api/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/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/steps

This REST API path provides actions and information about specific workflow steps

GET /api/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 elements (if neither list nor short options are passed as above).

GET /api/steps?action=list

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

/api/steps/{id_or_name}

This REST API path provides actions and information about specific workflow steps

GET /api/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: a list of REST Function Hash elements with the following additional key:
  • desc: the step description (as derived from the description of the primary step function)

/api/sync-events

This REST URI path provides actions and information about workflow synchronization events

GET /api/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

GET /api/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/sync-events/{type}

This REST URI path provides actions and information about workflow synchronization event types

GET /api/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

GET /api/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

PUT /api/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/sync-events/{type}/{key}

This REST URI path provides actions and information about a particular workflow synchronization event key

GET /api/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/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/system

This REST URI path provides actions and information for system functionality

GET /api/system

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

GET /api/system?action=echo

Description
Returns the arguments passed
Return Value
The arguments passed

GET /api/system?action=ping

Description
Returns "OK"
Return Value
This API returns "OK" upon successful execution

PUT /api/system?action=reloadRbac

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

PUT /api/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/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
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_ROTATE_LOG_FILES or OMQ::QR_LOGGER_CONTROL

PUT /api/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/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.
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: SHUTDOWN-ALREADY-IN-PROGRESS: system shutdown is already in progress
Note
requires permission OMQ::QR_SHUTDOWN
See also

PUT /api/system?action=shutdownWait

Description
Shuts down the system and returns when the system shutdown process is complete.
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/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/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/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/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 arguments (either as URI arguments or in the message body):
  • token: (required) the token string
Return Value
The username corresponding to the token if the token is valid otherwise NOTHING
Deprecated:
this function is kept only for backward compatibility with the old UI.
Errors
  • 400 Bad Request: missing "token" argument or invalid argument type
  • 409 Conflict: TOKEN-ERROR: invalid token

GET /api/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.

Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • ttl: (optional) duration of validity of the token in seconds; if not present, defaults to 10 minutes
Return Value
A string token to be used for websocket communication
Note
the maximum token duration is 1 hour

/api/system/alerts

This REST URI path provides actions and information related to system alerts

GET /api/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/system/alerts/ongoing

This REST URI path provides actions and information related to ongoing system alerts

GET /api/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/system/alerts/transient

This REST URI path provides actions and information related to transient system alerts

GET /api/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/system/api

This REST URI path provides actions and information about the system RPC API

PUT /api/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/system/health

This REST URI path provides actions and information about system health

GET /api/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/system/listeners

This REST URI path provides actions and information related to Qorus HTTP listeners

GET /api/system/listeners

Description
Returns a list of hashes of information about HTTP listeners
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 Listener Hash elements

POST /api/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/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/system/listeners/{id_or_name}

This REST URI path provides actions and information related to a specific HTTP listener

DELETE /api/system/listeners/{id_or_name}

Description
Stops the current listener
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

GET /api/system/listeners/{id_or_name}

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

GET /api/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/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

PUT /api/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/system/listeners/{id_or_name}?action=stop

Description
Stops the current listener
See also
This API is equivalent to DELETE /api/system/listeners/{id_or_name}; see that documentation for details.

/api/system/metadata

This REST URI path provides actions and information related to the system metadata cache

Since
Qorus 3.1.0

PUT /api/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/system/options

This REST URI path provides actions and information related to system options; see System Options for more information

GET /api/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/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/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/system/options/{options}

This REST URI path provides actions and information related to specific system options; see System Options for more information

GET /api/system/options/{options}

Description
Returns a hash describing the option
Return Value
This API returns a REST System Option Hash

PUT /api/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/system/props

This REST URI path provides actions and information related to a system properties.

GET /api/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/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/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/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/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/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/system/props/{domain}

This REST URI path provides actions and information related to a specific system property domain.

DELETE /api/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/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/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/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/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/system/props/{domain}/{key}

This REST URI path provides actions and information related to a specific system property key.

DELETE /api/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/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/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/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/system/rbac

GET /api/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/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/system/sessions

This REST URI path provides actions and information related to Qorus application sessions

GET /api/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/system/sqlcache

This REST API path provides actions and information related to the system SQL cache

Since
Qorus 3.1.0

GET /api/system/sqlcache

Description
Returns information about the system cache
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • system: returns information about system objects as well (in the "omq" datasource)
Return Value
This API returns a hash keyed by datasource name; values are hashes keyed by SQL object type (ex: "tables"); the values of this hash are hashes with the following keys:
  • count: the number of times accessed
  • created: the date/time the object was cached

PUT /api/system/sqlcache?action=clear

Description
Clears the SQL cache according to the arguments.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • datasource: (optional) a string giving the datasource to clear all objects for
  • name: (optional) the name of the object to clear; if this argument is given, then datasource must also be given
Return Value
This API returns "OK" upon successful execution

PUT /api/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/system/ui

This REST URI path provides actions and information related to the system UI

GET /api/system/ui

Description
Returns a list of child URI path components
Return Value
This API returns a list of child URI path components

/api/system/ui/extensions

This REST URI path provides actions and information related to system UI extensions

GET /api/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/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/system/ui/extensions/{name}

This REST URI path provides actions and information related to a specific system UI extension

GET /api/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/system/userhttp

This REST URI path provides actions and information about user HTTP services.

GET /api/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

/api/users

This REST URI path provides actions and information related to Qorus users

GET /api/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/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/users?action=current

Description
Returns a hash describing the current calling user
Return Value
This API returns a REST User Hash

GET /api/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/users/{user}

This REST URI path provides actions and information related to a particular user

DELETE /api/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/users/{user}

Description
Returns a hash describing the current user
Return Value
This API returns a REST User Hash

PUT /api/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/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/valuemaps

This URI path provides actions and information related to Qorus value maps

GET /api/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)

PUT /api/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/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/valuemaps/{id_or_name}

This URI path provides actions and information related to a specific value map

GET /api/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)

GET /api/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/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/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/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/valuemaps/{id_or_name}/{key}

This URI path provides actions and information related to a specific value map value

GET /api/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/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/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
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

PUT /api/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

PUT /api/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/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/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/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/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/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/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/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/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/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/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/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/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/workflows/{id_or_name}

This REST URI path provides actions and information about a particular workflow.

GET /api/workflows/{id_or_name}

Description
Returns a REST Workflow Description Hash for the current workflow
Return Value
This API returns a REST Workflow Description Hash for the current workflow

POST /api/workflows/{id_or_name}?action=createOrder

Description
Creates a workflow order data instance for the current workflow with the data passed as arguments
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • [staticdata]: the static data for the order; either this key or external_order_instanceid is required
  • [external_order_instanceid]: the external order instance ID for the workflow data; either this key or staticdata is required
  • [dynamicdata]: the initial dynamic data for the order
  • [orderkeys]: a hash of order keys for the order
  • [scheduled]: the earliest date and time the order can be processed; if this date is given as a future date/time value and a OMQ::StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to OMQ::StatScheduled instead of OMQ::StatReady
  • [priority]: the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • [status]: the initial order status (default OMQ::StatReady); must be either OMQ::StatReady or OMQ::StatBlocked
  • [parent_workflow_instanceid]: a loosely-coupled workflow that will be marked as the parent of this workflow
Return Value
a hash with the following key:
  • workflow_instanceid the workflow instance ID of the workflow order instance ID created
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_SUBMIT_ORDER
See also
omq.system.create-order()

PUT /api/workflows/{id_or_name}?action=decAutostart

Description
Decrements the autostart value on the current workflow.
Return Value
This API returns a hash with the following keys:
  • updated: True or False
  • autostart: the new autostart value
  • info: info about the workflow update action
  • stopped: the number of execution instances started
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-SETAUTOSTART-ERROR: autostart value cannot be negative; cannot change the autostart value on a workflow with the deprecated flag set
Note

PUT /api/workflows/{id_or_name}?action=disable

Description
Disables the current workflow.
Return Value
This API returns a hash with the following keys:
  • name: the workflow name
  • version: the workflow version
  • workflowid: the workflow ID
  • info: info about the workflow disable 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
Note

PUT /api/workflows/{id_or_name}?action=enable

Description
Enables the current workflow if it is disabled.
Return Value
This API returns a hash with the following keys:
  • name: the workflow name
  • version: the workflow version
  • workflowid: the workflow ID
  • info: info about the workflow 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
  • 409 Conflict: SHUTDOWN-IN-PROGRESS: disabled workflows cannot be enabled while the system is shutting down
  • 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

POST /api/workflows/{id_or_name}?action=execSynchronous

Description
Creates a new order for the current workflow and executes it synchronous mode. The call will normally return only after the workflow order 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):
  • [staticdata]: the static data for the order; either this key or external_order_instanceid is required
  • [external_order_instanceid]: the external order instance ID for the workflow data; either this key or staticdata is required
  • [dynamicdata]: the initial dynamic data for the order
  • [orderkeys]: a hash of order keys for the order
  • [priority]: the order priority (default OMQ::DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest
  • [parent_workflow_instanceid]: a loosely-coupled workflow that will be marked as the parent of this workflow
  • [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
  • 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
requires at least one of the following permissions: OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_EXEC_SYNC_WORKFLOW
See also

PUT /api/workflows/{id_or_name}?action=incAutostart

Description
Increments the autostart value for the current workflow.
Return Value
This API returns a hash with the following keys:
  • updated: True or False
  • autostart: the new autostart value
  • info: info about the workflow update action
  • started: the number of execution instances started
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-SETAUTOSTART-ERROR: cannot set a positive autostart value on a workflow with the deprecated flag set
Note

GET /api/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)

GET /api/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/workflows/{id_or_name}?action=reset

Description
Deletes the configuration for the current workflow from the cache; if there are any running execution instances, then the reset will cause the workflow to be reloaded from the database on their next iteration.
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_EXEC_CONTROL, or OMQ::QR_RESET_WORKFLOW

PUT /api/workflows/{id_or_name}?action=setAutostart

Description
Sets the autostart value for the current workflow.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • 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:
  • updated: True or False
  • autostart: the new autostart value
  • info: info about the workflow update action
  • started: if positive, then it is the number of execution instances started; if negative, its absolute value denotes the number of execution instances stopped.
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-SETAUTOSTART-ERROR: missing autostart argument; autostart value is negative; cannot set a positive autostart value on a workflow with the deprecated flag set
Note
  • requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_EXEC_CONTROL
  • workflows that have their autostart value changed from zero to a positive number will be started automatically; workflows that have their autostart value set to zero will be stopped immediately

PUT /api/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/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/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/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/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/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 (REST API v1 and v2) elements for the workflow errors for the current workflow corresponding to the arguments

POST /api/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 description of the error
  • error: (required string) the error string (ex: "SOCKET-SSL-ERROR")
  • forceworkflow: (optional) 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
  • retry_delay_secs: (optional int) an optional retry value in seconds (only used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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
  • 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 forceworkflow option as described above

POST /api/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 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 used if retry_flag is also True)
  • retry_flag: (optional bool) parsed with Qore::parse_boolean(); a retry flag value (if not present then False is assumed)
  • severity: (optional string) a severity code for the error (if not present OMQ::ES_Major is assumed); for possible values see Error Severity Codes
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 (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)
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 forceworkflow option as described above

/api/workflows/{id_or_name}/errors/{error}

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

DELETE /api/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/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/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/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/workflows/{id_or_name}/instances

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

GET /api/workflows/{id_or_name}/instances

Return Value
This API returns a list of hashes with the keys of REST Execution Instance Hash 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/workflows/{id_or_name}/orders

This REST URI path provides actions and information about workflow orders for the current workflow.

GET /api/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
  • 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/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/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/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/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/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 booelan 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/workflows/{id_or_name}/orders/{id}?action=block

Description
Blocks the current workflow order data instance by changing the status to OMQ::StatBlocked. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatBlocked status (unless the workflow instance is recovered back from OMQ::StatBlocked or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Return Value
This API returns a hash with the following keys:
  • workflow_status: the status of the workflow order
Errors
  • 409 Conflict: BLOCK-WORKFLOW-ERROR: invalid status, foreign session id, missing original status, unblock operation already in progress
  • 403 Forbidden: 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_BLOCK_WORKFLOW_ORDER
See also

PUT /api/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/workflows/{id_or_name}/orders/{id}?action=cancel

Description
Cancels the current workflow order data instance by changing its status to OMQ::StatCanceled. An exception will be thrown if the status is OMQ::StatInProgress. No further processing can be done on workflow order data instances with a OMQ::StatCanceled status (unless the workflow instance is recovered back from OMQ::StatCanceled or the status is first updated to OMQ::StatError and then to OMQ::StatRetry).
Return Value
This API returns a hash with the following keys:
  • 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: 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_CANCEL_WORKFLOW_ORDER
See also

PUT /api/workflows/{id_or_name}/orders/{id}?action=dynamicData

Description
Replaces the dynamic data for an existing order.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: (hash) the new dynamic data for the current workflow order; can also be 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
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

POST /api/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/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/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/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/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 arguments (either as URI arguments or in the message body):
  • note: the note to create on 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
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_SET_ORDER_INFO

PUT /api/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/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/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/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/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/workflows/{id_or_name}/orders/{id}?action=staticData

Description
Replaces the static data for an existing order.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • newdata: the new static data for the current workflow order; must be 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: ORDER-STATIC-DATA-ERROR: the new static data hash cannot be empty
Note
requires permission OMQ::QR_WORKFLOW_CONTROL, OMQ::QR_WORKFLOW_ORDER_CONTROL, or OMQ::QR_EDIT_WORKFLOW_DATA

PUT /api/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.
Return Value
This API returns a hash with the following keys:
  • workflow_status: the status of the workflow order
Errors
  • 409 Conflict: BLOCK-WORKFLOW-ERROR: invalid status, foreign session id, missing original status, unblock operation already in progress
  • 403 Forbidden: 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_BLOCK_WORKFLOW_ORDER
See also

PUT /api/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.
Return Value
This API returns a hash with the following keys:
  • 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: 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_CANCEL_WORKFLOW_ORDER
See also

PUT /api/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/workflows/{id_or_name}/orders/{id}?action=updateKeys

Description
Sets order keys for the current workflow order; any keys given here will replace existing order keys.
Arguments
This API takes the following hash arguments (either as URI arguments or in the message body):
  • orderkeys: (hash) the order keys to replace for the current workflow order
Return Value
This API returns a hash of all order keys for the order after updating
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: ORDER-KEYS-ERROR: the orderkeys argument was missing or not a hash
  • 409 Conflict: INVALID-WORKFLOW-KEY: an order key was given that is not valid for the workflow
  • 409 Conflict: DUPLICATE-KEY-VALUE: the same value may not appear more than once for any given key
Note
requires permission OMQ::QR_WORKFLOW_CONTROL or OMQ::QR_WORKFLOW_ORDER_CONTROL