 |
Qorus Integration Engine® Enterprise Edition 6.0.16_prod
|
|
Qorus Integration Engine® Enterprise Edition 6.0.16_prod
|
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.
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.
For the Python-based remote client, allowing users to work with remote Qorus instances over HTTP and WebSocket connections, which can be installed on any platform supporting a recent version of Python 3; see https://github.com/qoretechnologies/qorus-remote.
The Python client can be installed from pip with:
pip install qorus-remote
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 ([]),
System / General Task Overview
| Task | RBAC Permission(s) Required | Commands |
| Start Qorus | n/a | qctl startqorus [options] |
| Shutdown Qorus | SHUTDOWN | qctl stopqrest put system/shutdown |
| Restart Qorus | SHUTDOWN | qctl restartqrest 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, SET-PROPERTY, or DELETE-PROPERTY | oprop set domain key [value] |
| Delete a Class | CREATOR-CONTROL or CREATOR-DELETE | qrest del classes/name |
| Delete Qorus Objects | see PUT /api/latest/system/metadata?action=reload | oload -Xobjecttype:name:version -R |
| Check Global Config Item Value | LOGIN | qrest system/config/name/value |
| Set Global Config Item Value | SERVER-CONTROL | qrest put system/config/name value=qore-value |
| Delete Global Config Item Value | SERVER-CONTROL | qrest delete system/config/name |
| Live Upgrades | n/a - direct DB access | oload -lvR <release file> |
Workflow Task Overview
| Task | RBAC Permission(s) Required | Commands |
| List Running Workflows | LOGIN | ostatus -w |
| Disable a Workflow | WORKFLOW-CONTROL, GROUP-CONTROL, MODIFY-GROUP, or MODIFY-GROUP-STATUS | qrest put workflows/name/disable |
| Enable a Workflow | WORKFLOW-CONTROL, GROUP-CONTROL, 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, 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 Step Config Item Value | LOGIN | qrest workflows/workflow-name/stepinfo/step-name/config/<name> |
| Set Step Config Item Value | WORKFLOW-CONTROL, WORKFLOW-EXEC-CONTROL, or SET-STEP-CONFIG | qrest put workflows/workflow-name/stepinfo/step-name/config/name value=qore-value |
| Delete Step Config Item Value | WORKFLOW-CONTROL, WORKFLOW-EXEC-CONTROL, or SET-STEP-CONFIG | qrest delete workflows/workflow-name/stepinfo/step-name/config/name |
| Delete a Workflow | WORKFLOW-CONTROL, WORKFLOW-EXEC-CONTROL, or RESET-WORKFLOW | oload -Xworkflow:name:version -R |
Service Task Overview
| Task | RBAC Permission(s) Required | Commands |
| 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, GROUP-CONTROL, MODIFY-GROUP, or MODIFY-GROUP-STATUS | qrest put services/name/disable |
| Enable a Service | SERVICE-CONTROL, GROUP-CONTROL, 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[,...])" |
| Check Service Config Item Value | LOGIN | qrest services/service-name/config/<name> |
| Set Service Config Item Value | SERVICE-CONTROL, SET-SERVICE-CONFIG | qrest put services/service-name/config/name value=qore-value |
| Delete Service Config Item Value | SERVICE-CONTROL, SET-SERVICE-CONFIG | qrest delete services/service-name/config/name |
| Delete a Service | SERVICE-CONTROL or RESET-SERVICE | oload -Xservice:name:version -R |
Job Task Overview
| Task | RBAC Permission(s) Required | Commands |
| 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, GROUP-CONTROL, MODIFY-GROUP, or MODIFY-GROUP-STATUS | qrest put jobs/name/disable |
| Enable a Job | JOB-CONTROL, GROUP-CONTROL, MODIFY-GROUP, MODIFY-GROUP-STATUS | qrest put jobs/name/enable |
| Check Job Config Item Value | LOGIN | qrest jobs/job-name/config/<name> |
| Set Job Config Item Value | JOB-CONTROL, SET-JOB-CONFIG | qrest put jobs/job-name/config/name value=qore-value |
| Delete Job Config Item Value | JOB-CONTROL, SET-JOB-CONFIG | qrest delete jobs/job-name/config/name |
| Delete a Job | CREATOR-CONTROL or CREATOR-DELETE | qrest del jobs/name |
RBAC Task Overview
| Task | RBAC Permission(s) Required | Commands |
| 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 |
| 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 |
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.
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.
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
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 BYThen 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
The schema-tool program can be used to gather statistics on Oracle, MySQL, and PostgreSQL databases.
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]
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]
See Arch system service.
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 v6.0.16_prod (build HEAD-dc3a15fbfd6623f6a84d418221e052c8dea41f63), Copyright (C) 2003 - 2023 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.
Error: Cannot Open System Datasources
ERROR opening datasource omq: DBI:ORACLE:OCI-ERROR ERROR opening datasource omquser: DBI:ORACLE:OCI-ERROR cannot open system datasources, aborting
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
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)
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 auto-recover) to recover the previous instance |
Error: Unable to Create HTTP Server
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
| 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
2010.10.19 12:18:31.023745 T0: OMQ: Unable to load system services (SERVICE-ERROR: system service "name" does not exist)
| 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. |
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.
To view Qorus system options, use ostatus as follows:
unixprompt% ostatus -o
Output similar to the following should appear:
Qorus 6.0.16_prod 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 = FalseOption 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.
No error messages should appear. If an error message appears, see the following section for causes.
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.
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
Error: Invalid Option
OPTION-ERROR: one or more options given was invalid
| 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.
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.
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.
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 : "6.0.11"
schema-compatibility : "6.0.11"
schema-load-compatibility : "6.0.11"
arch : hash: (5 members)
directory : "/appl/logs/omq/arch" If an error message appears, see the following section for causes.
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.
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.
Error: Missing Parameter
ERROR: PARAMETER-ERROR: ‘key’ is a required parameter
| 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.
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 6.0.16_prod 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.
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.
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.
Error: Unknown Workflow
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" | 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.
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.
Error: Unknown Workflow
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" | 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.
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.
Error: Unknown Workflow
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" | 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.
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.
Error: Unknown Workflow
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" | 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.
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.
Error: Invalid Workflow Order Instance ID
WORKFLOW-ORDER-ERROR: there is no workflow_instanceid <x>
| Possible Cause | Action to Take |
| The ID is incorrect | Correct the ID and try the command again. |
Error: Invalid Workflow Order Data Instance Status
STATUS-ERROR: 01: can't update status 'C' (COMPLETE): {err: "STATUS-ERROR", status: "COMPLETE"}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.
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.
Error: Cannot Update Subworkflow Step
ERROR: PARAMETER-ERROR: cannot call skipStep() on a subworkflow step
| Possible Cause | Action to Take |
| The step ID refers to a subworkflow step | Correct the child workflow instead. |
Error: Invalid Step ID
ERROR: SKIP-STEP-ERROR: stepid <id>/<id> has not been executed in workflow_instance <id>
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: STEP-STATUS-ERROR: can’t update steps with status <status>
| 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.
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.
Error: Invalid Workflow Order Instance ID
ERROR: WORKFLOW-ERROR: workflow_instance_id <id> does not exist
| 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: WORKFLOW-STATUS-ERROR: <status>
"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.
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.
Error: Invalid Workflow Order Instance ID
ERROR: INVALID-WORKFLOW-ORDER-DATA-INSTANCE: workflow_instanceid <x> does not exist
| 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: CANCEL-WORKFLOW-STATUS-ERROR: <status>
"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.
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:
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.
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.Error: Workflow is not Cached
ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<id> 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.
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.
Error: Unknown Workflow>
ERROR: UNKNOWN-WORKFLOW: workflow <name>: 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.
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 COMPLETEIf an error message appears, see the following section for causes.
Error: No Such Workflow Order Data Instance
workflow_instanceid <id>: no results
| 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.
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.
Error: Invalid Workflow
ERROR: RESET-WORKFLOW-ERROR: workflow <name>/<version> is not currently 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.
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.
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.
Error: No Such Service
ERROR: SERVICE-ERROR: system service "<name>" does not exist
| 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: SERVICE-NO-METHOD: system service <name>/<ver> has not registered method "<method>" (available
methods: <list>) | 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.
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.
Error: No Such Service
ERROR: SERVICE-ERROR: system service "<name>" does not exist
| 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.
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.
Error: Unknown Service
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"
| 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.
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.
Error: Unknown Service
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"
| 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.
Upgrading a service involves the following steps:
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)>...
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.
Error: Unknown Job
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"
| 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.
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.
Error: Unknown Job
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"
| 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.
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.
Error: Unknown Job
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"
| 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.
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.
active argument to TrueError: Unknown Job
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"
| 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.
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.
"LOGIN" and "SHUTDOWN" permissionsEdit 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.
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.
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.
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.
Error: Invalid Role
ERROR: RBAC-ADD-USER-ERROR: role "operator2" is not currently 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: RBAC-ADD-USER-ERROR: user "fred" 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.
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.
Error: Invalid Role
INVALID-ROLE: role "operator2" 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
USER-ERROR: user "fred" 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.
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
If an error message appears, see the following section for causes.
Error: Invalid Role
ERROR: RBAC-ADD-USER-ERROR: cannot add user "fred"; role "operator2" is not currently 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: RBAC-ADD-USER-ERROR: user "fred" does not exist
| 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.
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
"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.
Error: Invalid Role
ERROR: RBAC-ADD-USER-ERROR: cannot add user "fred"; role "operator2" is not currently 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
INVALID-USER: user "fred" 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.
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.
Error: Communication, Authentication, and Environment Error
See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.
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.
Error: Invalid User
ERROR: RBAC-DELETE-USER-ERROR: user "fred" does not exist
| 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.
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.
Invalid User
INVALID-USER: user "fred" 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.
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.
Error: Communication, Authentication, and Environment Error
See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.
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.
Role Already Exists
RBAC-ADD-ROLE-ERROR: role "operator2" 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
RBAC-ADD-ROLE-ERROR: cannot add role "operator2"; permission "LOGIN1" is not currently 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.
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.
Error: Role Already Exists
ROLE-ERROR: ROLE "operator2" 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
INVALID-PERMISSION: PERMISSION "LOGIN1" 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.
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
+ 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.
Error: Invalid Role
ERROR: RBAC-UPDATE-ROLE-ERROR: role "operator2" does not exist
| 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: RBAC-UPDATE-ROLE-ERROR: cannot update role "operator2"; permission "LOGIN1" is not currently 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.
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.
Error: Invalid Role
INVALID-ROLE: ROLE "operator2" 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.
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.
Error: Invalid Role
RBAC-DELETE-ROLE-ERROR: role "operator2" does not exist
| 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.
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.
Error: Invalid User
ROLE-ERROR: role "operator2" 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.
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.
Error: Communication, Authentication, and Environment Error
See Common Client Errors for more information. These errors could affect any client, including Qorus command-line tools.
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.
Error: Permission Already Exists
ERROR: RBAC-ADD-PERMISSION-ERROR: permission "USER-PERMISSION-1" 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.
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.
Error: Permission Already Exists
ADD-PERMISSION-ERROR: PERMISSION "USER-PERMISSION-1" 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.
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.
Error: Invalid Permission
ERROR: RBAC-UPDATE-PERMISSION-ERROR: permission "USER-PERMISSION-1" does not exist
| 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.
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.
Error: Invalid Permission
INVALID-PERMISSION: PERMISSION "USER-PERMISSION-1" does not exist
| Possible Cause | Action to Take |
| The permission does not exist | Check the permission name and try the command again. |
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.
Error: Invalid Permission
ERROR: RBAC-DELETE-PERMISSION-ERROR: permission "USER-PERMISSION-1" does not exist
| 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: 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 | 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: RBAC-DELETE-PERMISSION-ERROR: permission "LOGIN" is a SYSTEM permission and cannot be deleted
| Possible Cause | Action to Take |
| Permission name was misspelled | Check the permission name and try again |
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.
Error: Invalid Permission
DELETE-PERMISSION-ERROR: permission "USER-PERMISSION-1" 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
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| 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
DELETE-PERMISSION-ERROR: permission "LOGIN" is a SYSTEM permission and cannot 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.
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:
cert and key option parameters)cert and key option parametersSystem 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}By default, only the superuser role has access to sensitive data APIs by default (Enterprise Edition only).
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:
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 dataqorus-sensitive-data.sensitive-data-purge-complete: set to False to prohibit purging of workflow orders with status COMPLETEqorus-sensitive-data.sensitive-data-purge-canceled: set to False to prohibit purging of workflow orders with status CANCELEDIt 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.
These errors could affect any Qorus client program that communicates with the Qorus process using the HTTP interface.
Error: Connection Error
ERROR: Qorus server at "http://localhost:8001" is down
SOCKET-CONNECT-ERROR: error in connect() (target: localhost:8001): Connection refused: 111
| 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 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 (Enterprise Edition only).
HTTP-CLIENT-RECEIVE-ERROR: HTTP status code 401 received: message: Unauthorized
| 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 authorization error message is returned (Enterprise Edition only).
AUTHORIZATION-ERROR: user "user1" does not have permission "WORKFLOW-CONTROL"
| 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: DBI:PGSQL:ERROR: could not connect to server: Connection refused
| 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 |