Qorus Integration Engine®  5.0.1_git
Operations Manual

Table of Contents

Introduction

Overview

This document is intended to provide a guide to usage of the Qorus Integration Engine system. For more detailed information on the system’s design, please see the System Reference Manual.

Common operational tasks are covered here, as well as common errors and some troubleshooting information.

Common tasks included:

Note that this manual does not cover performing common operational tasks from the Qorus Integration Engine Web UI; all tasks (aside from starting the system) can also be performed with the Qorus Web UI as well.

In addition to the topics above, database administration is a critical area that must be covered properly in order to ensure the correct operation of the system, in particular database free space (for example, the data and index tablespaces with Oracle and PostgreSQL installations) and transaction log space must be monitored closely, and all indexes must be kept current.

If indexes are invalidated for whatever reason, Qorus Integration Engine may deadlock (as row locks may be silently converted into table locks) or performance will suffer.

Database administration regarding basic tasks such as index maintenance and data deletion are documented in Database Maintenance And Administration, however detailed Oracle, MySQL, and PostgreSQL database administration is beyond the scope of this manual; make sure a competent DBA is monitoring your system any time Qorus is used for business-critical process automation.

Task Summary

For all the commands in this section, the UNIX or Windows environment must be set up properly to run the qore binary and the Qorus system. For more information on these requirements, see Installation Guide.

All commands should be typed on a single line. Text in italics should be replaced with the appropriate value. Optional arguments are enclosed in square brackets ([]),

Operational Task Overview

Task RBAC Permission(s) Required Commands
Start Qorus n/a qctl start
qorus [options]
Shutdown Qorus SHUTDOWN qctl stop
qrest put system/shutdown
Restart Qorus SHUTDOWN qctl restart
qrest put system/restart [restart=seconds]
Check System Options LOGIN ostatus -o
Set System Options OPTION-CONTROL qrest put system/options/set option=value[,...]
Redefine Datasources DATASOURCE-CONTROL or RESET-DATASOURCE oload or edit DB connection in the system DB, then: qrest put remote/datasources/reload
Rotate Log Files ROTATE-LOG-FILES qrest put system/rotateLogFiles
View System Properties LOGIN oprop get
Update System Properties SERVER-CONTROL or SET-PROPERTY or DELETE-PROPERTY oprop set domain key [value]
List Running Workflows LOGIN ostatus -w
Disable a Workflow WORKFLOW-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put workflows/name/disable
Enable a Workflow WORKFLOW-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put workflows/name/enable
Check Workflow Options LOGIN ostatus -wv
Set Workflow Options WORKFLOW-CONTROL or WORKFLOW-OPTION-CONTROL qrest put workflows/name/setOptions options="(option=value[,...])"
Reset a Workflow WORKFLOW-CONTROL or WORKFLOW-EXEC-CONTROL or RESET-WORKFLOW qrest put workflows/name/reset
Check System Status LOGIN ostatus -oS
Check Running Workflow Status LOGIN ostatus -w
Check Workflow Data Status CALL-SYSTEM-SERVICES-RO oview -ssg w:id
Check Service Status LOGIN ostatus -sv
Call a Service Method CALL-SYSTEM-SERVICES-RO or CALL-SYSTEM-SERVICES-RW qrest put services/name/method/call [args=...]
Disable a Service SERVICE-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put services/name/disable
Enable a Service SERVICE-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put services/name/enable
Set Service Options SERVICE-CONTROL or SET-SERVICE-OPTIONS qrest put services/name/setOptions options="(option=value[,...])"
Run a Job JOB-CONTROL or RUN-JOB qrest put jobs/name/run
Check Job Status LOGIN ojview
View Job Instance LOGIN ojview j:id
Set Job Options JOB-CONTROL or SET-JOB-OPTIONS qrest put jobs/name/setOptions options="(option=value[,...])"
Activate a Job JOB-CONTROL or MODIFY-JOB-STATUS qrest put jobs/name/setActive active=true
Deactivate a Job JOB-CONTROL or MODIFY-JOB-STATUS qrest put jobs/name/setActive active=false
Disable a Job JOB-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put jobs/name/disable
Enable a Job JOB-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put jobs/name/enable
List Interface Groups LOGIN qrest groups?short=1
Disable an Interface Group GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put groups/name/disable
Enable an Interface Group GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put groups/name/enable
Live Upgrades n/a - direct DB access oload -lvR <release file>
Online: Add a New User USER-CONTROL or ADD-USER qrest post users username=username,pass=pass,desc=descriptive name, roles="(role[,...])"
Online: Change Password USER-CONTROL or MODIFY-USER qrest put users/username/update [pass=pass,name=name, storage="(storage_hash)",roles="(role[,...])"]
Online: Change Your Own Password LOGIN qrest put users/_current_/update pass=password
Online: Add a New User Permission USER-CONTROL or ADD-PERMISSION qrest post perms name=name,desc=description
Online: Add a New Role USER-CONTROL or ADD-ROLE qrest post roles role=name,desc=description, perms="(perm[,...])"
Online: Delete a User USER-CONTROL or DELETE-USER qrest delete users/username
Online: Delete a User Permission USER-CONTROL or DELETE-PERMISSION qrest delete perms/name
Online: Delete a Role USER-CONTROL or DELETE-ROLE qrest delete roles/role
Offline: Add a New User n/a - direct DB access user-tool -Ausername:pass:role(s):"description"
Offline: Change Password n/a - direct DB access user-tool -dusername:pass=newpassword
Offline: Add a New User Permission n/a - direct DB access user-tool -Ppermissionname:"description"
Offline: Add a New Role n/a - direct DB access user-tool -Rrolename:"description":permission[,permission,...]
Offline: Delete a User n/a - direct DB access user-tool -Xuser:username
Offline: Delete a User Permission (Cascading) n/a - direct DB access user-tool -c -Xpermission:name
Offline: Delete a Role n/a - direct DB access user-tool -Xrole:name
Synchronize Offline RBAC Changes USER-CONTROL user-tool -s

Database Maintenance And Administration

In order for the system to perform properly, the system database must be properly maintained and administered. This is most important on Oracle, where maintaining up to date DB statistics and performing proper index maintenance can be critical to system performance.

Qorus Integration Engine includes some facilities for assisting DBAs with maintaining the database. These facilities are documented in this section.

Index Maintenance

On Oracle dataservers, indexes must be maintained; as data is changed or deleted from indexed tables, indexes become less efficient; the number of dead leaf nodes and the number of indirections grow, slowing down table accesses. When these parameters breach pre-defined maximum values; the indexes should be rebuilt.

Qorus has two different ways of analyzing and rebuilding Oracle indexes that need it: internally in the system, using the system.arch service, and from the command-line, using the schema-tool program.

Additionally, Qorus provides a facility for unconditionally rebuilding all indexes in a schema; for more information on this topic, see Unconditionally Rebuilding Indexes.

Analyzing and Rebuilding Oracle Indexes with schema-tool

To analyze and rebuild indexes on the entire system schema in Oracle using schema-tool, execute the following command:

unixprompt% schema-tool -R 

The thresholds by default are given in the following table:

Criteria Value
maximum index height 3
maximum percentage of deleted leaf nodes 20%

To override these values, use the –max-height and –max-leaf-pct options.

If either value is above the threshold, then the index will be rebuilt. The command used to rebuild the index is:

alter index [name] rebuild nologging compute statistics 

Note that indexes in any Oracle schema can be analyzed and rebuilt, as long as the Oracle user has permission to do so. To analyze and rebuild indexes in another schema, pass the name of the datasource as an argument to the -R option; for example:

unixprompt% schema-tool -R=billing 

Unconditionally Rebuilding Indexes

Indexes in the system schema can be unconditionally rebuilt using schema-tool as follows:

unixprompt% schema-tool -F 

To unconditionally rebuild indexes in another schema, pass the name of the datasource to the -F option as follows:

unixprompt% schema-tool -F=datasourcename 

On Oracle, the list of indexes in the schema is acquired executing the following SQL (note that partitioned indexes are ignored):

select index_name, tablespace_name from user_indexes
where partitioned = 'NO' and index_type != 'LOB'"

Then indexes are rebuilt with the following command:

alter index [name] rebuild nologging compute statistics 

On PostgreSQL, the list of indexes is acquired by executing the following SQL:

SELECT c.relname as name
FROM pg_catalog.pg_class c
     JOIN pg_catalog.pg_permissions r ON r.oid = c.relowner
     LEFT JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
     LEFT JOIN pg_catalog.pg_index i ON i.indexrelid = c.oid
     LEFT JOIN pg_catalog.pg_class c2 ON i.indrelid = c2.oid
WHERE n.nspname <> 'pg_catalog'
  AND n.nspname !~ '^pg_toast'
  AND pg_catalog.pg_table_is_visible(c.oid)
  and r.rolname = 'schemaname' and c.relkind = 'i'
ORDER BY

Then indexes are rebuilt with the following command:

reindex index [name] 

On MySQL, indexes are rebuilt by using the "repair table" command. A list of tables is acquired by executing "show tables". Then indexes on each table are rebuild by executing the following command on each table:

repair table [name] quick 

Gathering Table or Schema Statistics

The schema-tool program can be used to gather statistics on Oracle, MySQL, and PostgreSQL databases.

Gathering Statistics on an Entire Schema

To gather statistics on the entire system schema, execute the following command:

unixprompt% schema-tool -S 

Note that by giving a valid Qorus datasource name (defined in the Datasource Connections), you can analyze statistics on any datasource known to Qorus (as long as the user has the appropriate permissions); for example, to gather statistics on the schema defined by the datasource named billing, execute the following:

unixprompt% schema-tool -S=billing 

For Oracle, the following SQL is executed:

begin dbms_stats.gather_schema_stats(ownname => 'schemaname',
	estimate_percent => 10, granularity => 'all',
	method_opt => 'for all columns size auto',
	degree => dbms_stats.default_degree,
	options => 'gather auto', cascade => true );
end;

For PostgreSQL, the following command is executed:

analyze 

For MySQL, the following command is executed for each table in the schema (as determined by executing "show tables"):

analyze table [tablename] 

Gathering Statistics on a Table

To gather statistics on a particular table, in the system schema execute the following command:

unixprompt% schema-tool -T=tablename 

To gather statistics on a particular table in another schema in a defined datasource, type the following:

unixprompt% schema-tool -T=datasourcename=tablename 

For Oracle, the following SQL is executed:

begin dbms_stats.gather_table_stats (ownname => 'schemaname',
	tabname => 'tablename', partname => null,
	estimate_percent => dbms_stats.auto_sample_size,
	degree => 3, cascade => true);
end;

For PostgreSQL, the following command is executed:

analyze [tablename] 

For MySQL, the following command is executed:

analyze table [tablename] 

Deleting Old Data From the Database

See Arch system service.

Working With the System

Start Qorus Integration Engine

In order to start the Qorus Integration Engine system, log in with a user account with write access to the Qorus log directory, with read access to the Qorus configuration files (normally the UNIX user qorus), and the UNIX environment configured as specified in the installation instructions, and enter the following at the command line:

unixprompt% qorus [option=value ...] 

Output similar to the following should appear:

Qorus Integration Engine v5.0.1_git (build HEAD-ddc8d8fa5be11e018b7342ffa1b70d61e06aa547), Copyright (C) 2003 - 2016 Qore Technologies
auto-recover quark-1: no sessions need recovery
starting instance quark-1 on omq@omq (pgsql) with session ID 459
starting HTTP listener on: <all interfaces>:8001, <all interfaces>:8001, /tmp/qorus-sock-manatee-dev1
HTTP listener 0 started on ipv6[::]:8001
HTTP listener 3 started on unix:/tmp/qorus-sock-manatee-dev1

No error messages should appear. If an error message appears, see the following section for causes.

Note
See the System Reference Manual for more information on the Qorus startup sequence, system programs, and system options. In particular, note that there are functional limitations when starting more than one Qorus instance on the same database schema. These are documented in the Qorus Integration Engine System Reference Manual.
Common Errors Starting the System

Error: Cannot Open System Datasources

Error Message:
ERROR opening datasource omq: DBI:ORACLE:OCI-ERROR
ERROR opening datasource omquser: DBI:ORACLE:OCI-ERROR
cannot open system datasources, aborting 
Explanation:
The Qorus system cannot connect to one or more system datasources. The omq and omquser datasources must be accessible for the system to start. To get more detailed information, try to connect from the command-line with sqlplus (Oracle), mysql (MySQL) or psql (PostgreSQL), depending on the database server used for the system schema.
Possible Cause Action to Take
No TNSNAMES.ORA entry for Oracle Databases Have the DBA make the correct entries in the TNSNAMES.ORA file
Database is down Check with DBA and start database if necessary
Login or connection parameters are incorrect Edit the login parameters in options' qorus.systemdb
Network connectivity loss Check with network administrators to fix the problem

Error: Unable to Open Session

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to open session (ACTIVE-SESSION-ERROR: [instance name] sessionid 20 is currently active. If this is incorrect, then restart Qorus with auto-recover=True) 
Explanation:
There is an entry in the sessions table with this instance key and with status = ACTIVE. Check active sessions with schema-tool -L and the process list to verify if the instance is running or not.
Possible Cause Action to Take
The instance is already running Take no action (system is already running) or start the system with a new instance key and new HTTP server port.
The instance stopped abnormally Launch the instance with auto-recover=true (see qorus.auto-recover) to recover the previous instance

Error: Unable to Create HTTP Server

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to start HTTP server on "[host:]port" (HTTP-SERVER-ERROR: could not bind to socket "[host:]port": Address already in use), aborting 
Explanation:
The Qorus system could not open the port given with the qorus.http-server option because another process is already using that port.
Possible Cause Action to Take
Another process is already listening on this port Start the system with a different HTTP server port (change the qorus.http-server option), or stop the other process before trying to start Qorus on the same port.

Error: Cannot Load System Services

Error Message:
2010.10.19 12:18:31.023745 T0: OMQ: Unable to load system services (SERVICE-ERROR: system service "name" does not exist) 
Explanation:
The Qorus system could not load the system service listed in the error message.
Possible Cause Action to Take
The system has not been completely installed Make sure the system schema has been installed and all system services have been loaded in the database. Run schema-tool -Vv and see instructions in the Installation Guide for more information.
System datasource points to the wrong database Check that the omq datasource is correctly configured to access the Qorus system schema in the qorus.systemdb option.

Stop Qorus Integration Engine

To stop the Qorus system, use qctl to send a stop message to the server.

The system shutdown process proceeds as follows: first, workflows are stopped, then jobs, then services are stopped and unloaded. Because interfaces must complete any current processing before stopping, there can be a delay between sending the stop message and the time the system is fully stopped.

To shut down the system, execute the following command-line to send this command to the server:

unixprompt% qctl stop 

Output similar to the following should appear:

stopping cluster:
 + qorus-core: stopping workflow snapshot manager...
 + qorus-core: stopping job snapshot manager...
 + qorus-core: stopped snapshot managers
 + qorus-core: stopping all workflows
 + qorus-core: stopped all workflows
 + qorus-core: stopped all jobs
 + qorus-core: stopping all services
 + qorus-core: stopped user connections
 + qorus-core: stopped performance monitoring
 + qorus-core: stopped remote connections
 + qorus-core: stopped db connections
 + qorus-core: stopped segment manager
 + qorus-core: stopped workflow synchronization event manager
 + qorus-core: stopped all services
 + qorus-core: stopped performance cache manager
 + qorus-core: stopped workflow queue thread pool
 + qorus-core: stopped alert manager
 + qorus-core: closed application session
 + qorus-core: stopped user connection monitoring
 + qorus-core: stopped remote Qorus connection monitoring
 + qorus-core: stopped datasource connection monitoring
 + qorus-core: stopped FTP server
 + qorus-core: stopped HTTP server
 + qorus-core: stopped HTTP token store
 + qorus-core: stopped all server threads
 + qorus-master: qorus has been shut down
 + qorus-master: shutdown complete
done

No error messages should appear.

Note
For more information, see the System Reference Manual for more information on the Qorus shutdown sequence; for information on Qorus command-line programs, see Command-Line Programs, for API method information, see the Network System API, and see System Service Reference for more information on system service methods.

View System Options

To view Qorus system options, use ostatus as follows:

unixprompt% ostatus -o 

Output similar to the following should appear:

Qorus 5.0.1_git development-qore2-1 sessionid 1920 ((up 20 hours 2 minutes 32 seconds)
* auto-recover                    = True
* daemon-mode                     = True
* max-log-files                   = 5
* system-pool-minimum             = 3
* system-pool-maximum             = 10
  loglevel                        = 20000
  max-retries                     = 5
  max-async-retries               = 20
  recover_delay                   = 300
  async_delay                     = 1200
  detach-delay                    = 1200
  cache-max                       = 1000000
* logdir                          = "/opt/qorus/log/"
* http-server                     = "8001", "8001", "/tmp/qorus-sock-meteor-1"
* http-secure-server              = "8011{cert=$OMQ_DIR/etc/cert.pem;key=$OMQ_DIR/etc/key.pem;password=help}", "8111{cert=$OMQ_DIR/etc/cert2.pem;key=$OMQ_DIR/etc/key2.pem;password=test}"
* http-secure-certificate         =
* http-secure-private-key         =
* http-secure-private-key-password =
* instance-key                    = "meteor-1"
* rbac-security                   = True
* rbac-force-user                 = localhost="admin"
* option-file                     = "/opt/qorus/etc/options"
* dbparams-file                   =
  logfile-template                = "OMQ-$instance-$name.log"
  wf-logfile-template             = "OMQ-$instance-WF-$name.log"
  svc-logfile-template            = "OMQ-$instance-SVC-$name.log"
  job-logfile-template            = "OMQ-$instance-JOB-$name.log"
* force-gui-encoding              =
* max-events                      = 10000
  workflow-params                 =
* db-max-threads                  = 10
* audit                           = "*"
* max-service-threads             = 200
* compat-strict-bool-eval         = False
* compat-string-numbers           = False
* rbac-external                   = "QorusRbacOAuth2"
  debug-system                    = True
* defines                         = (QoreDebug="1", FAKE_NAS="1", SCMHUB_MOCK="1")
* auto-error-update               = True
* compat-http-utf8                = False
* transient-alert-max             = 1000
* alert-smtp-connection           =
* alert-smtp-to                   =
* alert-smtp-from                 = "alert_noreply@$instance"
* alert-smtp-interval             = 60
  alert-smtp-enable               = False
* alert-fs-full                   = 85
  sql-default-blocksize           = 5000
  sql-init-blocksize              = 200
* connection-modules              = "RabbitMQConnection", "JavaHttpConnection"
* dsp-warning-timeout             = 5000
* dsp-error-timeout               = 120000
  manage-interfaces               = True
  socket-warning-timeout          = 10000
  socket-min-throughput           = 20480
  socket-min-throughput-ms        = 1000
* autostart-interfaces            = True
  service-perf-events             = False
  workflow-perf-events            = True
  workflow-step-perf-events       = False
* mapper-modules                  = "EbsSingleTableInboundMapper"
* oracle-datasource-pool          = True
  vmap-size-threshold             = 100
  sync-delay                      = 3600
* systemdb                        = "pgsql:omq/omq@omq%meteor"
* stack-size                      =
* compat-allow-returns            = False
* compat-broken-cast              = False
* compat-broken-int-assignments   = False
* compat-broken-list-parsing      = False
* compat-broken-logic-precedence  = False
* compat-broken-loop-statement    = False
* compat-broken-operators         = False
* compat-broken-references        =
* compat-broken-sprintf           = False
* compat-permissive-api           = False
* compat-csvutil-force-empty-string =
* compat-wsdl-force-empty-string-is-nothing =
* compat-wsdl-allow-any-header    =
* debug-qorus-internals           = True
* sensitive-data-key              = "/opt/qorus/etc/sensitive_data.key"
* sensitive-value-key             = "/opt/qorus/etc/sensitive_value.key"
  purge-sensitive-data-complete   = False
  purge-sensitive-data-canceled   = False
* recovery-amount                 = 750
* recovery-currency               = "EUR"
* sla-max-events                  = 100
  sla-max-sync-secs               = 30
* network-key                     = "/opt/qorus/etc/network.key"
* node                            = (node1="192.168.0.28", node2="192.168.0.92")
* warning-process-memory-percent  = 50
* max-process-memory-percent      = 99
* allow-node-overcommit-percent   = 20
* compat-jni-types                = False
  compat-ignore-empty-order-key   = False
  workflow-modules                =
  service-modules                 =
  job-modules                     =
* default-datasource-coordinated  = False
* disable-tls-13                  = False
  dataprovider-modules            = "BB_SftpPollerData", "BB_Generic", "BB_FtpPollerData"
* remoteconnections-file          =
* unsupported-enable-tsdb         = False

Option names preceded by an asterisk are locked and cannot be changed after the system has started. These options can only be set in the System Options File file or on the command-line when the Qorus server process starts.

See Set System Options for information on how to change system options.

Note
See the System Reference Manual for more information on system options, Command-Line Programs for information about Qorus command-line programs, and the Network System API for more information on Qorus API methods.

No error messages should appear. If an error message appears, see the following section for causes.

Note
Use qrest to call the GET /api/latest/system/options API to retrieve system options using the API
Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Set System Options

To set Qorus system options, use qrest command to call the PUT /api/latest/system/options?action=set API as follows:

unixprompt% qrest put system/options/set <option>=<value> 

Output similar to the following should appear:

OK 

No error messages should appear. If an error message appears, see the following section for causes.

This will change the options in the running server. To make the options permanent and write them back out to the System Options File file, you can call the PUT /api/latest/system/options?action=flush as follows:

unixprompt% qrest put system/options/flush 
Note
See the System Reference Manual for more information on system options, Command-Line Programs for information about Qorus command-line programs, and the Network System API for more information on Qorus API methods.
Common Errors

Error: Invalid Option

Error Message:
OPTION-ERROR: one or more options given was invalid 
Explanation:
The option name given is not a valid system option.
Possible Cause Action to Take
Option name is incorrect Check the option name (options are case-sensitive) and try the command again with the correct option name. See System Options for a list of system options

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Persistently Redefine Datasource Connection Values

See also
Datasource Connections

Rotate Log Files

To rotate log files, use qrest to call the PUT /api/latest/system?action=rotateLogFiles API as follows:

unixprompt% qrest put system/rotateLogFiles 

Log files will be rotated (and old versions deleted as necessary) according to the configuration of the qorus.max-log-files system option. The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


View System Properties

To view system properties, call the appropriate REST API method with optional parameters using oprop as follows:

unixprompt% oprop get [domain [key]] 

If no key is given, all values in the domain are returned. If no domain is given, then all system properties are returned. Example output looks similar to the following:

hash: (4 members)
  omq : hash: (3 members)
    schema-version : "5.0.1"
    schema-compatibility : "5.0.1"
    schema-load-compatibility : "5.0.1"
  arch : hash: (5 members)
    directory : "/appl/logs/omq/arch" 

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Update System Properties

To update system properties, call the appropriate REST API method using oprop with the following parameters (note that to delete a key, do not send a value):

unixprompt% oprop set <domain> <key> [value] 

The output should look as follows:

INSERT 

If an error message appears, see the following section for causes.

Common Errors

Error: Missing Parameter

Error Message:
ERROR: PARAMETER-ERROR: ‘key’ is a required parameter 
Explanation:
One or more of the parameters to the method was not given.
Possible Cause Action to Take
Command-line was incomplete Check the command line and try it again with all required parameters.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Working with Workflows

List Running Workflow Execution Instances

To list the workflows running in a Qorus instance, use ostatus: Show System, Workflow, and Service Status as in the following example:

unixprompt% ostatus -w 

The output should look as follows (actual output will depend on instance parameters and which workflows have been started - also the output has been truncated for formatting purposes):

Qorus 5.0.1_git meteor-1 sessionid 2095 (up 20 hours 43 minutes 13 seconds)
workflows:
 +      1 CIP-TICKET-FAST-START                        1.0   NORMAL       (2020-09-17 12:22:22) <compat>
 +      2 PIP-PASSENGER-ORDER-EMAIL                    1.0   NORMAL       (2020-09-17 12:22:22) <compat>
 +      6 IT-00-MATERIAL_MOVEMENTS-WINCASH-TRANSFER-IN 1.0   NORMAL       (2020-09-17 12:22:24) <compat>

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Start a Workflow Execution Instance

To start a workflow execution instance and ensure that it is started automatically whenever the system is running and its dependencies are satisfied, use qrest to update the workflow's autostart value.

To start a workflow execution instance by setting the autostart value, enter the following at the command line:

unixprompt% qrest put workflows/<workflowname>/setAutostart autostart=<value> 

Output similar to the following should appear:

hash: (4 members)
  updated : True
  autostart : <value>
  info : "<workflow>> v<ver> (<id>) was updated with autostart = <value>"
  started : <value>

No error messages should appear. If an error message appears, see the following section for causes.

Note
If there is a significant amount of data for the workflow, the Qorus server will continue to perform event queue population in background after this command has returned. Any DB errors encountered by background threads will be reported in log files and will not be visible on the command line.
Common Errors

Error: Unknown Workflow

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found:
    class "workflows" has no subclass <name>" for HTTP method "PUT" 
Explanation:
Qorus could not find any definition for the workflow given.
Possible Cause Action to Take
Workflow name is incorrect Check the name and try again
The workflow has not yet been loaded Load the workflow with the oload program

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Disable Workflow

To stop all workflow execution instances for a particular workflow from running temporarily, disable the workflow with the following command:

unixprompt% qrest put workflows/<workflowname>/disable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  workflowid : <id>
  info : "disabled workflow <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Workflow

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found:
    class "workflows" has no subclass <name>" for HTTP method "PUT" 
Explanation:
Qorus could not find any definition for the workflow given.
Possible Cause Action to Take
Workflow name is incorrect Check the name and try again
The workflow has not yet been loaded Load the workflow with the oload program

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Enable Workflow

To enable a workflow, use the following command:

unixprompt% qrest put workflows/<workflowname>/enable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  workflowid : <id>
  info : "enabled workflow <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Workflow

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found:
    class "workflows" has no subclass <name>" for HTTP method "PUT" 
Explanation:
Qorus could not find any definition for the workflow given.
Possible Cause Action to Take
Workflow name is incorrect Check the name and try again
The workflow has not yet been loaded Load the workflow with the oload program

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Stop Workflow Permanently

To stop all workflow execution instances for a particular workflow from running now and in the future, set its autostart value to 0:

unixprompt% qrest put workflows/<workflowname>/setAutostart autostart=0 

Output similar to the following should appear:

hash: (4 members)
  updated : True
  autostart : 0
  info : "<workflow>> v<ver> (<id>) was updated with autostart = 0"
  started : -1

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Workflow

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found:
    class "workflows" has no subclass <name>" for HTTP method "PUT" 
Explanation:
Qorus could not find any definition for the workflow given.
Possible Cause Action to Take
Workflow name is incorrect Check the name and try again
The workflow has not yet been loaded Load the workflow with the oload program

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Queue Workflow Order Data Instance for Immediate Retry

To queue a workflow order data instance for immediate retry, execute the following command line:

unixprompt% qrest put orders/<id>/retry 

Output similar to the following should appear:

hash: (5 members)
  steps_updated : 0
  segments_updated : 1
  workflow_updated : True
  workflow_status : "RETRY"
  cached : False 

No error messages should appear. If an error message appears, see the following section for causes.

Note
For more information on Qorus programs like qrest, see Command-Line Programs; see System Options for more information on system options, see Network System API for more information on Qorus API methods
Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:
WORKFLOW-ORDER-ERROR: there is no workflow_instanceid <x> 
Explanation:
The workflow order data instance ID is not valid.
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:
STATUS-ERROR: 01: can't update status 'C' (COMPLETE): {err: "STATUS-ERROR", status: "COMPLETE"}
Explanation:
The workflow order data instance ID has a status that cannot be updated to RETRY.
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.
The status is incorrect Only workflow order data instances with status "ERROR", "ASYNC-WAITING", or "EVENT-WAITING" can be set to "RETRY". It is not possible to update workflow order data instances with other statuses to "RETRY".

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Skip Execution For a Step

Sometimes a step in a workflow order data instance cannot reach a "COMPLETE" status for reasons outside of the control of the workflow, but the rest of the workflow should be executed anyway on the order data instance. In these cases, the PUT /api/latest/orders/{id}?action=skipStep REST API method must be called with the workflow instance ID, the step ID, and the step index (0 for non-array steps) as arguments. These methods will only update steps with an "ERROR", "RETRY", "ASYNC-WAITING", or "EVENT-WAITING" status. For example, see the following command line:

        unixprompt% qrest put orders/<workflow_instanceid>/skipStep stepid=<stepid>,ind=<ind>,noretry=false

Output similar to the following should appear:

OK 

No error messages should appear. If an error message appears, see the following section for causes.

Note
For more information on Qorus programs like qrest, see Command-Line Programs; see Network System API for more information on Qorus API methods
Common Errors

Error: Cannot Update Subworkflow Step

Error Message:
ERROR: PARAMETER-ERROR: cannot call skipStep() on a subworkflow step 
Explanation:
The step ID refers to a subworkflow step and subworkflow steps cannot be skipped at the top level; the child workflow must be corrected.
Possible Cause Action to Take
The step ID refers to a subworkflow step Correct the child workflow instead.

Error: Invalid Step ID

Error Message:
ERROR: SKIP-STEP-ERROR: stepid <id>/<id> has not been executed in workflow_instance <id> 
Explanation:
The step ID and index combination could not be found in the STEP_INSTANCE table with this workflow_instanceid.
Possible Cause Action to Take
One of the IDs is incorrect Correct the ID and try the command again.

Error: Step Status Error

Error Message:
ERROR: STEP-STATUS-ERROR: can’t update steps with status <status> 
Explanation:
The step does not have a status that allows it to be skipped.
Possible Cause Action to Take
Step is "IN-PROGRESS" Wait until the step has finished executing and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Set a Workflow Order Data Instance’s Status to ERROR

To set workflow order data instance’s status to "ERROR", the PUT /api/latest/orders/{id}?action=setError REST API method must be called. Execute the following command-line to send this command to the server:

unixprompt% qrest put orders/<id>/setError 

Output similar to the following should appear:

hash: (4 members)
  steps_updated : 1
  segments_updated : 1
  workflow_status : "ERROR"
  old_status : "RETRY"
  priority : 500
  parent_info : hash: (2 members)
    parent_workflow_instanceid : 0
    subworkflow : 0

No error messages should appear. If an error message appears, see the following section for causes.

Note
For more information on Qorus programs like qrest, see Command-Line Programs; see Network System API for more information on Qorus API methods
Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:
ERROR: WORKFLOW-ERROR: workflow_instance_id <id> does not exist 
Explanation:
The workflow order data instance ID is not valid.
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:
ERROR: WORKFLOW-STATUS-ERROR: <status> 
Explanation:
The workflow order data instance ID has a status that cannot be updated to "ERROR"
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.
The status is incorrect Only workflow order data instances with statuses: "RETRY", "CANCELED", "ASYNC-WAITING", or "EVENT-WAITING" can be set to "ERROR". It is not possible to update workflow order data instances with other statuses to "ERROR".

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Set a Workflow Order Data Instance’s Status to CANCELED

To set workflow order data instance’s status to "CANCELED", the PUT /api/latest/orders/{id}?action=cancel REST API method must be called. Execute the following command line to send this command to the server:

unixprompt% qrest put orders/<id>/cancel 

Output similar to the following should appear:

hash: (1 member)
  workflow_status : "CANCELED" 

No error messages should appear. If an error message appears, see the following section for causes.

Note
For more information on Qorus programs like qrest, see Command-Line Programs; see Network System API for more information on Qorus API methods
Common Errors

Error: Invalid Workflow Order Instance ID

Error Message:
ERROR: INVALID-WORKFLOW-ORDER-DATA-INSTANCE: workflow_instanceid <x> does not exist 
Explanation:
The workflow order data instance ID is not valid.
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.

Error: Invalid Workflow Order Data Instance Status

Error Message:
ERROR: CANCEL-WORKFLOW-STATUS-ERROR: <status> 
Explanation:
The workflow order data instance ID has a status that cannot be updated to "CANCELED".
Possible Cause Action to Take
The ID is incorrect Correct the ID and try the command again.
The status is incorrect Only workflow order data instances with statuses: "RETRY", "ERROR", "ASYNC-WAITING", "WAITING", and "EVENT-WAITING" can be set to "CANCELED". It is not possible to update workflow order data instances with other statuses to "CANCELED".

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Perform a Live Upgrade of a Workflow

A live upgrade of a workflow entails updating a workflow definition for a workflow that has running execution instances.

To upgrade a workflow, the following steps must be taken:

  • Load the new workflow version in the database
  • Reset the cached workflow configuration

Workflows should be delivered with their own installation scripts and instructions; in this case follow the instructions delivered with your workflow’s installation script to load the new configuration into the Qorus system schema and reset the cached workflow configuration.

In case the workflow’s configuration should be updated by hand, follow the following steps.

For instance, if EXAMPLE-WORKFLOW 1.1 is being updated, the following command will load the new version of the workflow into the database and reset it in the live instance with the new configuration if it's currently running:

unixprompt% oload -lvR <file(s)>... 

Any workflows running will load the new configuration of the workflow from the database and use it when the workflow is reset. In this way workflow logic can be upgraded without causing an interruption of service.

Note
A workflow can only recover workflow order data instances that have the same workflow ID (name and version), for example, you cannot use EXAMPLE-WORKFLOW 1.1 to recover instances of EXAMPLE-WORKFLOW 1.0. If a bug is found in EXAMPLE-WORKFLOW 1.0 and a new version of the workflow must be released and instances of EXAMPLE-WORKFLOW 1.0 should be recovered by the new version, then EXAMPLE-WORKFLOW 1.0 should be loaded with a patched redefinition instead of creating EXAMPLE-WORKFLOW 1.1.
Common Errors

Error: Workflow is not Cached

Error Message:
ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<id> is not currently cached 
Explanation:
The workflow configuration cannot be reset because it is not currently cached.
Possible Cause Action to Take
Workflow is not running Normally installation scripts will specify that any updated workflows have their configurations reset, however if the workflow is not currently running, then it cannot be reset. In this case the error message can be ignored, because the workflow will run with the new configuration the next time it is run.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Check Workflow Order Overall Status

To check the overall status of processing of a workflow’s order data instances, there are several Qorus API methods that can be used. The oview program provides a user-friendly command-line interface to these methods.

For example, to see the overall status of EXAMPLE-WORKFLOW 1.1 in the last 24 hours:

unixprompt% oview EXAMPLE-WORKFLOW:1.1 

Assuming the workflow has been processing data in the last 24 hours, the output should look something like the following (the output has been truncated for formatting purposes):

                                          READY INCOMPLETE ASYNC-WAIT...
EXAMPLE-WORKFLOW        1.1                 20          2          3... 

If an error message appears, see the following section for causes.

Note
The oview program can be used to view overall status from one, many, or all workflows, to view detailed workflow/order information, and supports flexible time periods for aggregate reporting, depending on the options given on the command-line.
Common Errors

Error: Unknown Workflow>

Error Message:
ERROR: UNKNOWN-WORKFLOW: workflow <name>: does not exist 
Explanation:
The named workflow does not exist.
Possible Cause Action to Take
The workflow name is incorrect Check the workflow name and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Check Workflow Order Data Instance Status

To get detailed information on a single workflow order data instance’s status, there are several Qorus API methods that can be used. The oview program provides a user-friendly command-line interface to these methods.

For example, to see the detailed status of workflow order data instance ID 419649, with step and segment details:

unixprompt% oview w419649 -ssg 

Assuming the workflow has been processing data in the last 24 hours, the output should look something like the following (the output has been truncated for formatting purposes):

w:419619: PORTOUT_REQPORTING_OGW 1.0(1044)      (errors:  0) COMPLETE
    + SEGMENT  0: 005/005 steps executed                     COMPLETE
      + STEP: 716        createTransactionIdFunction 1.0     COMPLETE
      + STEP: 899        storePortingDateRequestFunction 1.0 COMPLETE
      + STEP: 900        checkMNPStatusFunction 1.0          COMPLETE
      + STEP: 996        checkPortingPinAndMSISDN 1.0        COMPLETE
      + STEP: 901     S  checkMSISDNBarredEAIFunction 1.0    COMPLETE
    + SEGMENT  1: 007/007 steps executed                     COMPLETE
      + STEP: 901     S  checkMSISDNBarredEAIFunction 1.0    COMPLETE
      + STEP: 902        checkLocalCalendarFunction 1.0      COMPLETE
      + STEP: 903        setMainMsisdnAndServicesForMsisdnsI COMPLETE
      + STEP: 904        checkIfVoiceAndVoiceBoxIncludedFunc COMPLETE
      + STEP: 905        copyReservationIDFromMsisdnNuevFunc COMPLETE
      + STEP: 907        updatePortingCalendarFunction 1.0   COMPLETE

If an error message appears, see the following section for causes.

Note
The oview program can be used to view overall status from one, many, or all workflows, to view detailed workflow/order information, and supports flexible time periods for aggregate reporting, depending on the options given on the command-line.
Common Errors

Error: No Such Workflow Order Data Instance

Error Message:
workflow_instanceid <id>: no results 
Explanation
The workflow order data instance ID does not exist.
Possible Cause Action to Take
The ID is incorrect Check the ID and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Reset a Workflow’s Configuration

Workflow configurations may need to be updated, for example, if a new configuration has been loaded into the database, or if a resource definition for a resource acquired during the workflow’s one-time-initialization is updated.

To reset a workflow’s cached configuration, the PUT /api/workflows/{id_or_name}?action=reset REST API method must be called as follows:

unixprompt% qrest put workflows/<name>/reset [version] 

Output similar to the following should appear:

workflow <name>/<version> has been deleted from the cache 

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Workflow

Error Message:
ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<version> is not currently cached 
Explanation:
The workflow’s cached configuration cannot be reset because it is not cached.
Possible Cause Action to Take
Workflow name or version is incorrect Check the input and try the command again with the correct parameters.
Workflow is not cached Take no action

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Order Instance Notes

Each workflow instance (order instance) can contain unlimited notes. Operators can store additional info or reference to tracking systems etc.

Relevant REST APIs:

Notes are displayed in the user interface.

Working With Services

Call a Service Method

Use the qrest command to call a service method. Using this command, parameters can also be easily passed to the method as well. If the service is not already loaded, then it is loaded and initialized before the method is called.

The syntax is as follows:

unixprompt% qrest put services/<name>/<method>/call [args=...] 

The command’s output is dependent on the service method being called.

If an error message appears, see the following section for causes.

Common Errors

Error: No Such Service

Error Message:
ERROR: SERVICE-ERROR: system service "<name>" does not exist 
Explanation:
The service does not exist in the Qorus database.
Possible Cause Action to Take
The service name is incorrect Check the service name and type and try the command again.

Error: No Such Method

Error Message:
ERROR: SERVICE-NO-METHOD: system service <name>/<ver> has not registered method "<method>" (available
    methods: <list>) 
Explanation:
The method does not exist in this service.
Possible Cause Action to Take
The method name is incorrect Check the method name against the list returned in the error message, and try the

command again.


Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Stop or Unload a Service

To stop a service, it must be unloaded from the Qorus service cache by calling the PUT /api/latest/services/{id_or_name}?action=unload REST API method as follows:

unixprompt% qrest put services/<name>/unload 

If the service is currently loaded, then it will be unloaded. If it is running, it will be stopped before it’s unloaded. The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Note
Because services are loaded and initialized automatically when a method is called, stopping or unloading a service will only be effective if no more calls to that service are made either internally or externally.
Common Errors

Error: No Such Service

Error Message:
ERROR: SERVICE-ERROR: system service "<name>" does not exist 
Explanation:
The service does not exist in the Qorus database.
Possible Cause Action to Take
The service name is incorrect Check the service name and type and try the command again
The service is not currently loaded Take no action, because the service has either already been unloaded or was never loaded

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Enable Service

To enable a service, use the following command:

unixprompt% qrest put services/<name>/enable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  serviceid : <id>
  info : "enabled service <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Service

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "services" has no subclass "name" for HTTP method "PUT"
Explanation:
The service does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The service name is incorrect Check the service name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Disable Service

To disable a service so that it will not be run automatically and cannot be run manually, disable it with the following command:

unixprompt% qrest put services/<name>/disable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  serviceid : <id>
  info : "disabled service <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Service

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "services" has no subclass "name" for HTTP method "PUT"
Explanation:
The service does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The service name is incorrect Check the service name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Perform a Live Upgrade of a Service

Upgrading a service involves the following steps:

  • Load the new version of the service in the database.
  • Reset the service

Use the ostatus -sv command to verify that the correct version of the service is loaded.

For instance if user service "service" version 1.0 is being replaced with "service" version 1.1, then the following commands will perform a live upgrade of the service:

unixprompt% oload -lvR <file(s)>...  

Working With Jobs

Run a Job Manually

Use the qrest command to call the PUT /api/latest/jobs/{id_or_name}?action=run REST API method to run a job as follows:

unixprompt% qrest put jobs/<name>/run [args=...] 

The output should look as follows:

hash: (2 members)
  job_instanceid : 858593
  status : "COMPLETE"

If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Job

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "jobs" has no subclass "name" for HTTP method "PUT"
Explanation:
The job does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The job name is incorrect Check the job name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Enable Job

To enable a job, use the following command:

unixprompt% qrest put jobs/<name>/enable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  jobid : <id>
  info : "enabled job <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Job

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "jobs" has no subclass "name" for HTTP method "PUT"
Explanation:
The job does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The job name is incorrect Check the job name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Disable Job

To disable a job so that it will not be run automatically and cannot be run manually, disable it with the following command:

unixprompt% qrest put jobs/<name>/disable 

Output similar to the following should appear:

hash: (4 members)
  name : "<name>"
  version : "<ver>"
  jobid : <id>
  info : "disabled job <name> v<ver> (<id>)"

No error messages should appear. If an error message appears, see the following section for causes.

Common Errors

Error: Unknown Job

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "jobs" has no subclass "name" for HTTP method "PUT"
Explanation:
The job does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The job name is incorrect Check the job name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Deactivate Job

To deactive a job so that it will not be run automatically but can still be run manually on demand, deactivate it with the following command:

unixprompt% qrest put jobs/<name>/setActive active=false 

Output similar to the following should appear:

hash: (4 members)
  jobid : <id>
  name : "<name>"
  active : False
  info : "jobid <id> "<name>" stopped and set to inactive"

No error messages should appear. If an error message appears, see the following section for causes.

Note
Reactivate the job by changing the active argument to True
Common Errors

Error: Unknown Job

Error Message:
DATASTREAM-CLIENT-RECEIVE-ERROR: HTTP status code 404 received: message: "Not Found": 404 Not Found: class "jobs" has no subclass "name" for HTTP method "PUT"
Explanation:
The job does not exist in the Qorus metadata cache.
Possible Cause Action to Take
The job name is incorrect Check the job name and type and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Working With Role-Based Access Control

Enable or Disable RBAC Security

Edit the System Options File file, and ensure a line appears as follows:

qorus.rbac-security: true 

Then restart the server. To disable RBAC security, change "true" in the above line to "false", or comment out the line and restart the Qorus server.

Note
You must also ensure that at least one user has both the "LOGIN" and "SHUTDOWN" permissions

Set Default RBAC User For Hosts Or IP Ranges

Edit the System Options File file, and ensure a line appears for each host or ip range as follows:

qorus.rbac-force-user: <host|ip-range>=<user> 

Then restart the server.

The user parameter must be set to a valid user; every unauthenticated connection from the given host or IP range will be made with the user given on the line. The qorus.rbac-force-user option may be given any number of times in the System Options File file.

IP ranges must be specified using ‘*’ as a wildcard as in the following examples:

qorus.rbac-force-user: 192.168.*=user
qorus.rbac-force-user: 10.135.11.*=remote-user 

Hostnames are given literally:

qorus.rbac-force-user: localhost=admin 

Changes to the System Options File file only take effect when the Qorus server is restarted.

List All Users

To list all users in Qorus, we use the user-tool program to do an offline listing (user-tool accesses the Qorus database directly and therefore can be used when the database is online but the Qorus server is offline).

unixprompt% user-tool -ll 

All user information is displayed except password information. The output should look as follows (use only one "l" above to display the users without permission lists; note that the output has been truncated for formatting purposes):

 USER: "admin" (Administrator) provider: db
  * created: 2015-08-04 14:14:57.000000 Tue +02:00 (CEST) modified: 2015-08-04 14:14:57.000000 Tue +02:00 (CEST)
  * (ROLE) superuser
+ USER: "dcm" (User used by DCM to call web services) provider: db
  * created: 2016-03-01 14:32:11.000000 Tue +01:00 (CET) modified: 2016-03-01 14:32:11.000000 Tue +01:00 (CET)
  * (ROLE) remote
+ USER: "wincash" (User used by Wincash to call web services) provider: db
  * created: 2016-02
...

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Create a New User (Online)

This action requires the "USER-CONTROL" permission.

To create a new user online (while the system is running, in a way that the new user is immediately available to make a connection) from an existing role, call the POST /api/latest/remote/user REST API method as follows:

unixprompt% qrest post users username=<name>,pass=<pw>,desc="<desc>",roles=<role(s)...> 

For example:

unixprompt% qrest post users username=fred,pass=mypass123,desc="Fred Smith",roles=operator 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
ERROR: RBAC-ADD-USER-ERROR: role "operator2" is not currently cached 
Explanation:
The role does not exist or has not yet been cached.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again
The role has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: User Already Exists

Error Message:
ERROR: RBAC-ADD-USER-ERROR: user "fred" already exists 
Explanation:
The user already exists.
Possible Cause Action to Take
The user already exists Check the user name and try again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any network client, including Qorus command-line tools.


Create a New User (Offline)

To create a new user while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -A<name>:"<pass>":<role(s),...>:"<description>" 

For example:

unixprompt% user-tool -Afred:mypass123:operator:"Fred Smith" 

All user information is displayed except password information. The output should look as follows (the output has been truncated for formatting purposes):

+ creating operator USER "fred" (Fred Smith):
  * adding role "operator"

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
INVALID-ROLE: role "operator2" does not exist 
Explanation:
The role does not exist.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.

Error: User Already Exists

Error Message:
USER-ERROR: user "fred" already exists 
Explanation:
The user already exists.
Possible Cause Action to Take
The user already exists Check the user name and try again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a User (Online)

This action requires the "USER-CONTROL" permission (unless the current user’s password is being updated, in which case "LOGIN" is sufficient).

To update an existing user online (while the system is running, in a way that the changes take effect immediately) call the PUT /api/latest/users/{user} REST API method as follows (at least one of the hash options must be given):

unixprompt% qrest put users/<username> [pass=<pass>,name=<name>,storage=<hash>,roles=<role,...>] 

For example:

unixprompt% qrest put users/fred name="Fred Smith-Smyth",pass=new_password 

The output should look as follows:

OK 
Note
Note that if a new role list is given, the new list will replace the old list entirely.

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
ERROR: RBAC-ADD-USER-ERROR: cannot add user "fred"; role "operator2" is not currently cached
Explanation:
The role does not exist or has not yet been cached.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.
The role has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Invalid User

Error Message:
ERROR: RBAC-ADD-USER-ERROR: user "fred" does not exist 
Explanation:
The user does not exist or has not yet been cached.
Possible Cause Action to Take
The user does not exist Check the username and try the command again.
The user has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a User (Offline)

To update an existing user while Qorus is offline; we use the user-tool program as follows (at least the name or pass options have to be used):

unixprompt% user-tool -d<name>:[pass=<pass>,name=<name>,roles=<role,...>] 

For example:

unixprompt% user-tool -dfred:pass=new_password,name="Fred Smythe" 

The output should look as follows

+ USER "fred" updated 
Note
The "user-tool -R" program option can use used to add individual roles to an existing user, "user-tool -O" deletes individual roles from users. Don’t forget to call "user-tool -s" after or while making changes with user-tool to synchronize the RBAC cache with the database.

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
ERROR: RBAC-ADD-USER-ERROR: cannot add user "fred"; role "operator2" is not currently cached
Explanation:
The role does not exist or has not yet been cached.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.
The role has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Invalid User

Error Message:
INVALID-USER: user "fred" does not exist 
Explanation:
The user does not exist.
Possible Cause Action to Take
The user does not exist Check the username and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Change the Current User’s Password (Online)

To change your own user’s password online (while the system is running, in a way that the change takes effect immediately) call the PUT /api/latest/users/{user} REST API method as follows:

unixprompt% qrest put users/_current_ pass=<new_pass> 

For example:

unixprompt% qrest put users/_current_ pass=new_password 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Delete a User (Online)

This action requires the "USER-CONTROL" permission.

To delete an existing user online (while the system is running, in a way that the changes take effect immediately) call the DELETE /api/latest/users/{user} REST API method as follows:

unixprompt% qrest delete users/<name> 

For example:

unixprompt% qrest delete users/fred 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid User

Error Message:
ERROR: RBAC-DELETE-USER-ERROR: user "fred" does not exist 
Explanation:
The user does not exist or has not yet been cached.
Possible Cause Action to Take
The user does not exist Check the username and try the command again.
The user has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Delete a User (Offline)

To delete an existing user while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -Xuser:<name> 

For example:

unixprompt% user-tool -Xuser:fred 

The output should look as follows:

+ USER "fred" deleted (11 permissions cleared) 

If an error message appears, see the following section for causes.

Common Errors

Invalid User

Error Message:
INVALID-USER: user "fred" does not exist 
Explanation:
The user does not exist.
Possible Cause Action to Take
The user does not exist Check the username and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


List All Roles

To list all roles in Qorus, we use the user-tool program to do an offline listing (user-tool accesses the Qorus database directly and therefore can be used when the database is online but the Qorus server is offline).

unixprompt% user-tool -rr 

All role information is displayed. The output should look as follows (use only one "r" above to display the roles without permission lists; note that the output has been truncated for formatting purposes):

+ ROLE: "superuser" (superuser with all system permissions) created: 2018-12-22 18:32:54.306733 Sat +01:00 (CET) modified: 2018-12-22 18:32:54.306733 Sat +01:00 (CET)
  * (PERMISSION) SYSTEM: LOGIN
  * (PERMISSION) SYSTEM: SHUTDOWN
  * (PERMISSION) SYSTEM: WORKFLOW-CONTROL
  * (PERMISSION) SYSTEM: EDIT-WORKFLOW-DATA
  * (PERMISSION) SYSTEM: EXEC-SYNC-WORKFLOW
  * (PERMISSION) SYSTEM: SENSITIVE-DATA-CONTROL
  * (PERMISSION) SYSTEM: SERVICE-CONTROL
  * (PERMISSION) SYSTEM: CALL-USER-SERVICES-RW
  * (PERMISSION) SYSTEM: CALL-SYSTEM-SERVICES-RW
  * (PERMISSION) SYSTEM: USER-CONTROL
  * (PERMISSION) SYSTEM: OPTION-CONTROL
  * (PERMISSION) SYSTEM: SUBMIT-ORDER
  * (PERMISSION) SYSTEM: ROTATE-LOG-FILES
  * (PERMISSION) SYSTEM: DATASOURCE-CONTROL
  * (PERMISSION) SYSTEM: GROUP-CONTROL
  * (PERMISSION) SYSTEM: SERVER-CONTROL
  * (PERMISSION) SYSTEM: JOB-CONTROL
  * (PERMISSION) SYSTEM: SCHEMA-CONTROL
  * (PERMISSION) SYSTEM: USER-CONNECTION-CONTROL
  * (PERMISSION) SYSTEM: SERVER-CONNECTION-CONTROL
  * (PERMISSION) SYSTEM: FILESYSTEM-CONTROL
  * (PERMISSION) SYSTEM: MAPPER-CONTROL
  * (PERMISSION) SYSTEM: VALUE-MAP-CONTROL
  * (PERMISSION) SYSTEM: SLA-CONTROL
  * (PERMISSION) SYSTEM: DEBUG-CONTROL
  * (PERMISSION) SYSTEM: REMOTE-DEPLOYMENT
  * (PERMISSION) SYSTEM: REMOTE-DELETE-INTERFACE
  * (PERMISSION) SYSTEM: REMOTE-RELEASE
  * (PERMISSION) SYSTEM: KILL-PROCESS
  * (PERMISSION) SYSTEM: LOGGER-CONTROL
  * (PERMISSION) SYSTEM: DATA-PROVIDER-CONTROL
  * (PERMISSION) SYSTEM: TYPE-CACHE-CONTROL
  * (PERMISSION) SYSTEM: SET-PIPELINE-CONFIG
  * (PERMISSION) SYSTEM: SET-FSM-CONFIG
  * (GROUP) DEFAULT(0)

+ ROLE: "operator" (operator profile) created: 2015-08-04 14:14:44.000000 Tue +02:00 (CEST) modified: 2016-03-29 15:10:55.000000 Tue +02:00 (CEST)
  * (PERMISSION) SYSTEM: LOGIN
  * (PERMISSION) SYSTEM: SHUTDOWN
  * (PERMISSION) SYSTEM: WORKFLOW-CONTROL
  * (PERMISSION) SYSTEM: EDIT-WORKFLOW-DATA
...

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Create a Role (Online)

This action requires the "USER-CONTROL" permission.

To create a new role online (while the system is running, in a way that the changes take effect immediately) call the POST /api/latest/roles REST API method (to create a new role from scratch) or the POST /api/latest/roles/{role}?action=clone REST API method as follows:

unixprompt% qrest post roles role=<name>,desc="<desc>",perms=<permissions>,groups=<groups> 

For example:

unixprompt% qrest post roles role=operator2,desc="Limited Operator",perms=LOGIN,CALL-SYSTEM-SERVICES-RO,CALL-USER-SERVICES-RO,OPTION-CONTROL,groups=DEFAULT 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Role Already Exists

Error Message:
RBAC-ADD-ROLE-ERROR: role "operator2" already exists 
Explanation:
The role already exists.
Possible Cause Action to Take
The role already exists Check the role name and try again, or modify the role if needed

Error: Invalid Permission

Error Message:
RBAC-ADD-ROLE-ERROR: cannot add role "operator2"; permission "LOGIN1" is not currently cached 
Explanation:
The permission does not exist or has not yet been cached.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.
The permission has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Create a Role (Offline)

To create a new role while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -R<name>:"<description>":<permission>[,<permission>...][:<group>[,<group>...]] 

For example:

unixprompt% user-tool -Roperator2:"Limited Operator":LOGIN,CALL-SYSTEM-SERVICES-RO,CALL-USER-SERVICES-RO,OPTION-CONTROL

The output should look as follows:

+ ROLE "operator2" (Limited Operator) created with 4 permissions 

If an error message appears, see the following section for causes.

Common Errors

Error: Role Already Exists

Error Message:
ROLE-ERROR: ROLE "operator2" already exists 
Explanation:
The role already exists.
Possible Cause Action to Take
The role already exists Check the role name and try again, or modify the role if needed

Error: Invalid Permission

Error Message:
INVALID-PERMISSION: PERMISSION "LOGIN1" does not exist 
Explanation:
The permission does not exist.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a Role (Online)

This action requires the "USER-CONTROL" permission.

To update an existing role online (while the system is running, in a way that the changes take effect immediately) call the PUT /api/latest/roles/{role} REST API method as follows (note that permissions can be relative; ex: +LOGIN,-OPTION-CONTROL):

unixprompt% qrest put roles/<name> [desc=<desc>,perms=<permission,...>,groups=<group,...>]

For example:

unixprompt% qrest put roles/operator2 desc="New Operator Role",perms=-SHUTDOWN,+OPTION-CONTROL,+WORKFLOW-CONTROL

The output should look as follows:

OK 
Note
Note that if a new permission list is given without leading + or - characters, the new list will replace the old list entirely. The "user-tool -U" program option can use used to add or remove individual permissions to an existing role. Don’t forget to call "user-tool -s" after or while making changes with user-tool to synchronize the RBAC cache with the database.

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
ERROR: RBAC-UPDATE-ROLE-ERROR: role "operator2" does not exist 
Explanation:
The role does not exist or has not yet been cached.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.
The role has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Invalid Permission

Error Message:
ERROR: RBAC-UPDATE-ROLE-ERROR: cannot update role "operator2"; permission "LOGIN1" is not currently cached
Explanation:
The permission does not exist or has not yet been cached.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.
The permission has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a Role (Offline)

To update an existing role while Qorus is offline; we use the user-tool program as follows (at least one of the desc, permissions, or groups options has to be used):

unixprompt% user-tool -Udesc="<description>" 

For example:

unixprompt% user-tool -Uoperator2:desc="New Operator Role" 

The output should look as follows:

+ ROLE "operator2" updated 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
INVALID-ROLE: ROLE "operator2" does not exist 
Explanation:
The role does not exist.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Delete a Role (Online)

This action requires the "USER-CONTROL" permission.

To delete an existing role online (while the system is running, in a way that the changes take effect immediately) call the DELETE /api/latest/roles/{role} REST API method as follows:

unixprompt% qrest delete roles/<name> 

For example:

unixprompt% qrest delete roles/operator2 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Role

Error Message:
RBAC-DELETE-ROLE-ERROR: role "operator2" does not exist 
Explanation:
The role does not exist or has not yet been cached.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.
The role has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Delete a Role (Offline)

To delete an existing role while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -Xrole:<name> 

For example:

unixprompt% user-tool -Xrole:operator2 

The output should look as follows:

+ ROLE "operator2" deleted (4 permissions cleared) 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid User

Error Message:
ROLE-ERROR: role "operator2" does not exist 
Explanation:
The role does not exist.
Possible Cause Action to Take
The role does not exist Check the role name and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


List All Permissions

To list all permissions in Qorus, we use the user-tool program to do an offline listing (user-tool accesses the Qorus database directly and therefore can be used when the database is online but the Qorus server is offline).

unixprompt% user-tool -L 

All "SYSTEM" and "USER" permissions are displayed. The output should look as follows (note that the output has been truncated for formatting purposes):

+ PERMISSION SYSTEM: "LOGIN": Allows logging in to the system
+ PERMISSION SYSTEM: "SHUTDOWN": Allows shutting down the system
+ PERMISSION SYSTEM: "WORKFLOW-CONTROL": Allows starting, stopping, ...
+ PERMISSION SYSTEM: "SERVICE-CONTROL": Allows services to be stopped / deleted
+ PERMISSION SYSTEM: "EDIT-WORKFLOW-DATA": Allows workflow data to be edited
+ PERMISSION SYSTEM: "CALL-USER-SERVICES-RO": Allows read-only user services ...
+ PERMISSION SYSTEM: "CALL-USER-SERVICES-RW": Allows all user services to be ...
+ PERMISSION SYSTEM: "CALL-SYSTEM-SERVICES-RO": Allows read-only system ...
+ PERMISSION SYSTEM: "CALL-SYSTEM-SERVICES-RW": Allows all system services ...
+ PERMISSION SYSTEM: "USER-CONTROL": Allows creating, deleting, changing ...
+ PERMISSION SYSTEM: "OPTION-CONTROL": Allows changing system options
+ PERMISSION SYSTEM: "SUBMIT-ORDER": Allows submitting order data for a workflow
+ PERMISSION SYSTEM: "ROTATE-LOG-FILES": Allows rotating log files
+ PERMISSION SYSTEM: "EXEC-SYNC-WORKFLOW": Allows executing workflows ...
...

If an error message appears, see the following section for causes.

Common Errors

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Create a New User Permission (Online)

This action requires the "USER-CONTROL" permission.

To create a new user permission online (while the system is running, in a way that the changes take effect immediately) call the POST /api/latest/perms REST API method as follows:

unixprompt% qrest post perms name=<name>,desc="<description>" 

For example:

unixprompt% qrest post perms name=USER-PERMISSION-1,desc="User Permission 1" 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Permission Already Exists

Error Message:
ERROR: RBAC-ADD-PERMISSION-ERROR: permission "USER-PERMISSION-1" already exists 
Explanation:
The permission already exists.
Possible Cause Action to Take
The permission already exists Check the permission name and try again, or modify the permission if needed

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Create a New User Permission (Offline)

To create a new user permission while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -P<name>:"<description>" 

For example:

unixprompt% user-tool -PUSER-PERMISSION-1:"User Permission 1" 

The output should look as follows:

+ PERMISSION USER "USER-PERMISSION-1" (User Permission 1) created 

If an error message appears, see the following section for causes.

Common Errors

Error: Permission Already Exists

Error Message:
ADD-PERMISSION-ERROR: PERMISSION "USER-PERMISSION-1" already exists 
Explanation:
The permission already exists.
Possible Cause Action to Take
The permission already exists Check the permission name and try again, or modify the permission if needed

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a User Permission (Online)

This action requires the "USER-CONTROL" permission.

To update the description for an existing user permission online (while the system is running, in a way that the changes take effect immediately) call the PUT /api/latest/perms/{perm} REST API method as follows:

unixprompt% qrest put perms/<name> desc=<description> 

For example:

unixprompt% qrest put perms/USER-PERMISSION-1 desc="New Operator Permission" 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Permission

Error Message:
ERROR: RBAC-UPDATE-PERMISSION-ERROR: permission "USER-PERMISSION-1" does not exist 
Explanation:
The permission does not exist or has not yet been cached.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.
The permission has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Update a User Permission (Offline)

To update an existing user permission while Qorus is offline; we use the user-tool program as follows (at least the name or pass options have to be used):

unixprompt% user-tool -E<name>:"<description>" 

For example:

unixprompt% user-tool -EUSER-PERMISSION-1:"New Operator Permission" 

The output should look as follows:

+ PERMISSION "USER-PERMISSION-1" updated 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Permission

Error Message:
INVALID-PERMISSION: PERMISSION "USER-PERMISSION-1" does not exist 
Explanation:
The permission does not exist.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.

Delete a User Permission (Online)

This action requires the "USER-CONTROL" permission.

To delete an existing user permission online (while the system is running, in a way that the changes take effect immediately) call the DELETE /api/latest/perms/{perm} REST API method as follows:

unixprompt% qrest delete perms/<name> 

For example:

unixprompt% qrest delete perms/USER-PERMISSION-1 

The output should look as follows:

OK 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Permission

Error Message:
ERROR: RBAC-DELETE-PERMISSION-ERROR: permission "USER-PERMISSION-1" does not exist 
Explanation:
The permission does not exist or has not yet been cached.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.
The permission has been created in the database but has not been cached Call "user-tool -s" to synchronize the RBAC cache with the database and try the command again.

Error: Permission Is Associated with One Or More Users or Roles

Error Message:
ERROR: RBAC-DELETE-PERMISSION-ERROR: permission "USER-PERMISSION-1" is referenced by one of more users;
    remove the permission from all users and roles before deleting or use user-tool to perform an offline cascading
    delete of the permission 
Explanation:
The permission cannot be deleted because it is associated with one or more users or roles.
Possible Cause Action to Take
The permission is associated with one or more users or roles Remove the permissions from the users and roles ("user-tool -w[permission] -r[permission]" will list all users and roles using the permission) and try again, or execute "user-tool -c -Xpermission:[permission]" to perform a cascading delete of the permission.

Error: Permission Is System Permission

Error Message:
ERROR: RBAC-DELETE-PERMISSION-ERROR: permission "LOGIN" is a SYSTEM permission and cannot be deleted
Explanation:
The permission cannot be deleted because it is a system permission. Only user permissions can be deleted.
Possible Cause Action to Take
Permission name was misspelled Check the permission name and try again

Delete a User Permission (Offline)

To delete an existing user permission while Qorus is offline; we use the user-tool program as follows:

unixprompt% user-tool -Xpermission:<name> 

For example:

unixprompt% user-tool -Xpermission:USER-PERMISSION-1 

If the permission is not associated to any users or roles, the output should look as follows:

+ PERMISSION "USER-PERMISSION-1" deleted (0 role, 0 user references deleted) 

If an error message appears, see the following section for causes.

Common Errors

Error: Invalid Permission

Error Message:
DELETE-PERMISSION-ERROR: permission "USER-PERMISSION-1" does not exist 
Explanation:
The permission does not exist.
Possible Cause Action to Take
The permission does not exist Check the permission name and try the command again.

Error: Permission Is Associated with One Or More Users or Roles

Error Message:
DELETE-PERMISSION-ERROR: The following users reference permission "USER-PERMISSION-1": list: ("username"), to delete all references, specify -cascade or -c on the command-line
Explanation:
The permission cannot be deleted because it is associated with one or more users or roles.
Possible Cause Action to Take
The permission is associated with one or more users or roles Remove the permissions from the users and roles ("user-tool -w[permission] -r[permission]" will list all users and roles using the permission) and try again, or execute "user-tool -c -Xpermission:[permission]" to perform a cascading delete of the permission.

Error: Permission Is System Permission

Error Message:
DELETE-PERMISSION-ERROR: permission "LOGIN" is a SYSTEM permission and cannot be deleted 
Explanation:
The permission cannot be deleted because it is a system permission. Only user permissions can be deleted.
Possible Cause Action to Take
Permission name was misspelled Check the permission name and try again.

Error: Communication, Authentication, and Environment Error

See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.


Working With Sensitive Data

Configuring an HTTPS Listener

In order for Qorus Integration Engine to process sensitive data, an HTTPS listener must be configured for Qorus, because sensitive data APIs are only usable from encrypted interfaces.

To configure an HTTPS listener, an X.509 certificate and private key must be generated; self-signed certificates may also be used if appropriate for your organization and use case.

An example command that can be used to generate a self-signed X.509 certificate with openssl 1.1.1+ with a validity period of 365 days and without a password for the private key with hostnames myhostname and myhostname.local and IP address 192.168.0.151 is as follows:

openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes -keyout key.pem   -out cert.pem -subj "/CN=myhostname"   -addext "subjectAltName=DNS:myhostname,DNS:myhostname.local,IP:192.168.0.151"

The HTTPS X.509 certificate file (in this example, "cert.pem") and the private key file ("key.pem") should be copied to $OMQ_DIR/etc and then can be configured in one of two ways:

  1. add the certificate and key file names to the qorus.http-secure-certificate and qorus.http-secure-private-key options in the System Options File, respectively for use with all HTTPS listeners, and then define at least one HTTP listener in the qorus.http-secure-server option (without the cert and key option parameters)
  2. add the certificate and key file names to the qorus.http-secure-server option in the System Options File using the cert and key option parameters

System Options File Examples:

# global X.509 cert and key on two HTTPS listeners
qorus.http-secure-certificate: $OMQ_DIR/etc/cert.pem
qorus.http-secure-private-key: $OMQ_DIR/etc/key.pem
qorus.http-secure-server: 192.168.20.77:8085,192.168.99.124:18005
# Two HTTPS listeners with different certificates and keys
qorus.http-secure-server: 192.168.20.77:8085{cert=$OMQ_DIR/etc/cert1.pem,key=$OMQ_DIR/etc/key1.pem},192.168.99.124:18005{cert=$OMQ_DIR/etc/cert2.pem,key=$OMQ_DIR/etc/key2.pem}

Setup Roles with Permissions to Access and Modify Sensitive Data

By default, only the superuser role has access to sensitive data APIs by default.

The following permissions need to be added appropriately to roles to allow users to view and manipulate sensitive data:

See the following sections for information on how to update roles:

Purging Sensitive Data

Sensitive data can be purged automatically from the system by using the following options:

However, to keep sensitive data online for a longer period for operational reasons (for example, the CANCELED status is not always used as a final status by an organization but rather in some cases could be subject to uncanceling and further processing), then one or more of these options can be set to False and the qorus-sensitive-data job can be activated.

To activate the qorus-sensitive-data job, the PUT /api/latest/jobs/{id_or_name}?action=setActive REST API can be used as in the following example:

qrest put jobs/qorus-sensitive-data/setActive active=true

By default, this job is scheduled to run once a day at 3 a.m. and will delete sensitive data when the workflow order's modified date is at least 6 months in the past and the workflow order has a status of COMPLETE or CANCELED.

The behavior of this job can be modified by setting the following system properties:

  • qorus-sensitive-data.sensitive-data-cutoff-months: set to an integer number of months giving the minimum age of the data
  • qorus-sensitive-data.sensitive-data-purge-complete: set to False to prohibit purging of workflow orders with status COMPLETE
  • qorus-sensitive-data.sensitive-data-purge-canceled: set to False to prohibit purging of workflow orders with status CANCELED
Note
if system options qorus.purge-sensitive-data-complete and qorus.purge-sensitive-data-canceled are set to True, then no new sensitive data will be left in the database after workflow orders get a final status of either COMPLETE or CANCELED. In this case, there is no reason to active this job.

It is possible to delete sensitive data from a workflow order regardless of its status by calling the DELETE /api/latest/orders?action=purgeSensitiveData API with the force option set to True by an authorized user with the DELETE-SENSITIVE-DATA or SENSITIVE-DATA-CONTROL permission. Note that in this case further processing of the workflow order may not be possible due to the missing data; use this option with great care.

See also

Common Client Errors

These errors could affect any Qorus client program that communicates with the Qorus process using the HTTP interface.


Error: Connection Error

Error Message:
ERROR: Qorus server at "http://localhost:8001" is down 
SOCKET-CONNECT-ERROR: error in connect() (target: localhost:8001): Connection refused: 111 
Explanation:
The client program could not connect the Qorus HTTP server.
Possible Cause Action to Take
The system is not running Check the system's status (with the ps command on UNIX/Linux), if it’s already been shut down, then no further action need be taken
The client URL (hostname and/or port) is incorrect Verify that the URL is correct and edit the System Options File file as needed.
The system is running but has not yet fully shut down. If the system has already stopped the HTTP server, but has not yet exited, then this error could appear. Usually the system process will terminate within a few seconds after shutting down the HTTP server. If it does not, it could be because a running service refuses to stop. If the process does not terminate in a reasonable time after the HTTP server has stopped (the amount of time may vary if there are any user services loaded that take an unusually long time to stop), then the only option left is to kill the Qorus processes manually. If the session was not closed, then the next time the Qorus process is launched; the qorus.auto-recover option must be set to true.

Error: Authentication Error

When Qorus Role-Based Access Control (RBAC) security is enabled, all network clients must provide a username and password to communicate with the server. All unauthenticated connections will be rejected by the server.

Error Message:
HTTP-CLIENT-RECEIVE-ERROR: HTTP status code 401 received: message: Unauthorized 
Explanation:
The Qorus HTTP server rejected the connection because authentication information was missing or invalid and no host or IP overrides exist for the client.
Possible Cause Action to Take
Authentication information is missing in the HTTP request Include a username and password in the request URL (i.e. http://user:pass@host:port) or, to allow unauthenticated connections from a certain host or IP address range, configure the qorus.rbac-force-user option in the System Options File file and restart the Qorus server to assume a default user for all unauthenticated connections from that host or IP address range.
Password is incorrect Correct the password in the URL and try again.

Error: Authorization Error

When Qorus Role-Based Access Control (RBAC) security is enabled, only authenticated users can connect, and each user has a set of permissions that allow the user to perform certain actions or classes of actions in the server. If the user does not have the required permission, an error message is returned.

Error Message:
AUTHORIZATION-ERROR: user "user1" does not have permission "WORKFLOW-CONTROL" 
Explanation:
Qorus denied the request to perform the action because the authenticated user does not have sufficient privileges to perform the action. One or more permissions are needed that the user does not have.
Possible Cause Action to Take
User does not have the required permission Use another username that has the permission or add the permission to your user and try again.

Error: Database Connection Error

Error Message: (error message may differ according to the database used):
ERROR: DBI:PGSQL:ERROR: could not connect to server: Connection refused 
Explanation:
The database could not be reached or (depending on the error message) the login parameters were invalid.
Possible Cause Action to Take
The database connection parameters are incorrect Check the entry in the qorus.systemdb for the connection string and try again. Verify connectivity with sqlplus (Oracle), psql (PostgreSQL), or mysql (MySQL)
The database is down Restart the database and try again