Qorus Integration Engine®  4.0.3.p2_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?action=shutdown
ocmd shutdown
Restart Qorus SHUTDOWN qctl restart
qrest put system?action=restart[;restart=seconds]
Check System Options LOGIN ostatus -o
Set System Options OPTION-CONTROL qrest put system/options?action=set option=value[,...]
ocmd set-option option=value[,...]
Redefine Datasources DATASOURCE-CONTROL or RESET-DATASOURCE oload or edit DB connection in the system DB, then: qrest put remote/datasources?action=reload
Rotate Log Files ROTATE-LOG-FILES qrest put system?action=rotateLogFiles
ocmd rotate-log-files
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?action=disable
Enable a Workflow WORKFLOW-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put workflows/name?action=enable
Check Workflow Options LOGIN ostatus -wv
Set Workflow Options WORKFLOW-CONTROL or WORKFLOW-OPTION-CONTROL qrest put workflows/name?action=setOptions\;options="(option=value[,...])"
Reset a Workflow WORKFLOW-CONTROL or WORKFLOW-EXEC-CONTROL or RESET-WORKFLOW qrest put workflows/name?action=reset
ocmd reset-workflow name
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?action=call [args=...]
ocmd omq.system.service.servicename.methodname [args]
ocmd omq.user.service.servicename.methodname [args]
Disable a Service SERVICE-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put services/name?action=disable
Enable a Service SERVICE-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put services/name?action=enable
Set Service Options SERVICE-CONTROL or SET-SERVICE-OPTIONS qrest put services/name?action=setOptions\;options="(option=value[,...])"
Run a Job JOB-CONTROL or RUN-JOB qrest put jobs/name?action=run
ocmd job.run name
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?action=setOptions\;options="(option=value[,...])"
Activate a Job JOB-CONTROL or MODIFY-JOB-STATUS qrest put jobs/name?action=setActive\;active=true
Deactivate a Job JOB-CONTROL or MODIFY-JOB-STATUS qrest put jobs/name?action=setActive\;active=false
Disable a Job JOB-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put jobs/name?action=disable
Enable a Job JOB-CONTROL or GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put jobs/name?action=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?action=disable
Enable an Interface Group GROUP-CONTROL or MODIFY-GROUP or MODIFY-GROUP-STATUS qrest put groups/name?action=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[,...])"
ocmd omq.system.add-user username password description role(s) groups
Online: Change Password USER-CONTROL or MODIFY-USER qrest put users/username?action=update [pass=pass,name=name,storage="(storage_hash)",roles=&quot(role[,...])"]
ocmd omq.system.update-user username pass=newpassword
Online: Change Your Own Password LOGIN qrest put users/_current_?action=update pass=password
ocmd omq.system.update-current-user pass=newpassword
Online: Add a New User Permission USER-CONTROL or ADD-PERMISSION qrest post perms name=name,desc=description
ocmd omq.system.add-permission permissionname description
Online: Add a New Role USER-CONTROL or ADD-ROLE qrest post roles role=name,desc=description,perms="(perm[,...])"
ocmd omq.system.add-role rolename description permissions groups
Online: Delete a User USER-CONTROL or DELETE-USER qrest delete users/username
ocmd omq.system.delete-user username
Online: Delete a User Permission USER-CONTROL or DELETE-PERMISSION qrest delete perms/name
ocmd omq.system.delete-permission permissionname
Online: Delete a Role USER-CONTROL or DELETE-ROLE qrest delete roles/role
ocmd omq.system.delete-role rolename
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 

Analyzing and Rebuilding Oracle Indexes with the system.arch Service

The arch.analyze_rebuild_indexes() method will perform index analysis and rebuilding in a manner similar to schema-tool.

The system.arch service uses the following system parameters (set with the system.prop service):

Parameter Name Default Meaning
ora-idx-max-height 3 maximum index height threshold
ora-idx-max-pct-del-leaf 20 maximum percentage of deleted leaf nodes

To call this method manually from the command-line, type:

unixprompt% ocmd omq.system.service.arch.analyze_rebuild_indexes 

Check the service’s log file for information about what actions were taken.

To just analyze indexes without rebuilding them, pass a boolean True or non-zero integer as the first argument to the method as follows:

unixprompt% ocmd omq.system.service.arch.analyze_rebuild_indexes true 

The results of the index analysis can be found in the service’s log file.

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 v4.0.3.p2_git (build HEAD-f861b98481a8cec7e7c10716b6c31391df8efb97), 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, either the omq.system.shutdown() or the omq.system.shutdown-wait() API method must be called by sending an appropriately formatted request to Qorus’s HTTP server (Note that the omq.system.shutdown() message is asynchronous; it queues the system exit, whereas the omq.system.shutdown-wait() method returns when the system is shut down).

The system shutdown process proceeds as follows: first, all executing workflows must terminate, and then all running services must be stopped and deleted. Therefore there could be a delay between executing the omq.system.shutdown() command 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% ocmd shutdown-wait 

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, 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.
Common Errors Stopping the System

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.


Error: System is Already Shutting Down

Error Message:
ERROR system shutdown is already in progress 
Explanation:
The system is already shutting down. Once the system shutdown command has been received, the shutdown process cannot be stopped. It could take some time for all running workflows to terminate and for all running services to stop, so if the shutdown command is sent after it has already been received, and before the Qorus HTTP server is stopped, this error message will be the result.
Possible Cause Action to Take
System is still shutting down Wait for all running workflow execution instances to terminate and the system should shut down cleanly afterwards.
A deadlock has occurred Deadlocks can occur for several reasons; for example, if someone locks an object in the Qorus system schema by hand (for example, by leaving an uncommitted transaction open) then a deadlock could happen. In this case, the locked database objects should be unlocked, which should resolve the situation. In the case of another unforeseen error, the Qorus process must be killed and the application session recovered when Qorus is next launched.

View System Options

To view Qorus system options, the omq.system.get-option-info() api method must be called by sending an appropriately-formatted request to the Qorus HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ostatus -o 

Output similar to the following should appear:

Qorus 4.0.3.p2_git development-qore2-1 sessionid 1920
* auto-recover                    = True
* daemon-mode                     = True
* max-log-files                   = 10
* system-pool-minimum             = 3
* system-pool-maximum             = 20
  verbose                         = 11
  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-manatee-dev1"
* http-secure-server              = "8002"
* http-secure-certificate         = "/opt/qorus/etc/cert.pem"
* http-secure-private-key         = "/opt/qorus/etc/key.pem"
* http-secure-private-key-password =
* instance-key                    = "manatee-dev1"
* rbac-security                   = True
* rbac-force-user                 = localhost="admin"
* option-file                     = "/opt/qorus/etc/options"
* force-gui-encoding              =
* max-events                      = 1000
  workflow-params                 =
* db-max-threads                  = 10
* audit                           =
* max-service-threads             = 200
* compat-strict-bool-eval         = False
* compat-string-numbers           = False
* rbac-external                   =
  debug-system                    = True
* defines                         = (FAKE_NAS="1")
* auto-error-update               = True
* compat-http-utf8                = True
* transient-alert-max             = 1000
* alert-smtp-connection           = "smtp-test"
* alert-smtp-to                   = "nicholsman@gmail.com"
* 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              =
* 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                  = "/opt/qorus/user/modules/CustomTableInboundMapper.qm"
* oracle-datasource-pool          = True
  vmap-size-threshold             = 100
  sync-delay                      = 3600
* 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-permissive-api           = False
* compat-csvutil-force-empty-string =
* compat-wsdl-force-empty-string-is-nothing =
* compat-wsdl-allow-any-header    =
* debug-qorus-internals           =
* sensitive-data-key              = "/home/petrytar/devel_release/etc/sensitive_data.key"
* sensitive-value-key             = "/home/petrytar/devel_release/etc/sensitive_value.key"
  purge-sensitive-data-complete   = True
  purge-sensitive-data-canceled   = True
* recovery-amount                 = 750
* recovery-currency               = "USD"
* sla-max-events                  = 100
  sla-max-sync-secs               = 30
* network-key                     = "/home/petrytar/devel_release/etc/network.key"
* node                            = node1="192.168.20.182"
* warning-process-memory-percent  = 30
* max-process-memory-percent      = 60
* flush-status                    = False
  tibco-daemon                    =
  tibco-network                   =
  tibco-service                   =
  tibco-timeout                   = 90000

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.

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 in a running process, the omq.system.set-option() api method must be called by sending an appropriately-formatted request to the Qorus HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-option <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 omq.system.flush-options() as follows:

unixprompt% ocmd flush-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.
Common Errors

Error: Invalid Option

Error Message:
ERROR: 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

Since Qorus 4 - all database connections are part of Datasource Connections

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


Rotate Log Files

To rotate log files, the omq.system.rotate-log-files() API method must be called. This can be done with the ocmd program as follows:

unixprompt% ocmd omq.system.rotate-log-files 

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 : "4.0.3.7"
    schema-compatibility : "4.0.3.7"
    schema-load-compatibility : "4.0.3.7"
  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, the omq.system.get-workflow-info() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server. The ostatus: Show System, Workflow, and Service Status program provides a user-friendly command-line interface to this method, for 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 4.0.3.p2_git psft-sit-av2s329t-1 sessionid 352
workflows:
 W    1 ACTIVATE-ACCOUNT          1.0   NORMAL         768/ 2 itera...
 W    2 ACTIVATE-CUSTOMER         1.0   NORMAL         671/ 2 itera...
 W    3 ACTIVATE-RESERVED-NUMBERS 1.0   NORMAL           0/ 2 itera...
 W    4 COLL-PSFT-BRIDGE          1.0   NORMAL        1416/ 2 itera...
 W    5 DEACTIVATE-SUBSCRIBER     1.0   NORMAL         161/ 2 itera...
 W    6 MAINTAIN-CUSTOMER         1.0   NORMAL          19/ 1 itera... 

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 an execution instance of a Qorus workfow, the name, version, and mode are required parameters to the omq.system.start-workflow() API method. Furthermore, workflow execution instance options can be given.

To start a workflow execution instance, enter the following at the command line:

unixprompt% ostart <workflowname> [version] [mode] 

If the mode parameter is present, it must be one of the following:

  • NORMAL: the workflow execution instance will start processing new orders (corresponds to OMQ::WM_Normal)
  • RECOVERY: the workflow execution instance will not process new orders, but only continue processing workflow order data instances that need error recovery (corresponds to OMQ::WM_Recovery)

Output similar to the following should appear:

started with ID <id> 

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

Note
If there is a significant number 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:
ERROR: NO-SUCH-WORKFLOW: <name>/<version> 
Explanation:
Qorus could not find any definition for the workflow name and version given.
Possible Cause Action to Take
Workflow name and/or version is incorrect Check the name and version and try again
The workflow has not yet been loaded Load the workflow with the oload program

Error: System is Shutting Down

Error Message:
ERROR: cannot start new workflows because the system is shutting down 
Explanation:
The shutdown command has been received and system shutdown is in progress.
Possible Cause Action to Take
System is shutting down After the system shuts down, restart it and then start the workflow.

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 a Workflow Execution Instance By ID

To retrieve a list of running workflow execution instances and their IDs, use the "ostatus -w" command (see ostatus: Show System, Workflow, and Service Status).

To stop a workflow execution instance, enter the following at the command line:

unixprompt% ostop <id> 

Output similar to the following should appear:

workflow with execution ID <id> is being stopped 

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

Common Errors

Error: Invalid Workflow ID

Error Message:
ERROR there is no workflow with execution ID <id> 
Explanation:
The ID does not correspond to a running workflow execution instance.
Possible Cause Action to Take
The ID is invalid. Check the list of running workflow execution instances and their IDs with "ostatus -w" 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 Workflow Execution Instances by Name

To stop workflow execution instances by name, the omq.system.stop-workflow() command must be sent to the server with the workflow name and an optional version as parameters. The ostop command provides a user-friendly command-line interface to this function.

To stop a workflow execution instance, enter the following at the command line:

unixprompt% ostop <name> [version] 

Output similar to the following should appear:

<number> instances of <name>/[<version>,*] <is|are> being stopped 

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

Common Errors

Error: Unknown Workflow

Error Message:
ERROR no instances of workflow <name>/<ver> are running 
Explanation:
Qorus is not currently running any instances of the workflow name and version given.
Possible Cause Action to Take
Workflow name and/or version is incorrect Check the name and version and try again. To get a list of running workflow execution instances (with names, versions, ids, etc), execute "ostatus -w"

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 All Workflow Execution Instances

To stop all running workflow execution instances, call the appropriate REST API method using the ostop program as follows:

unixprompt% ostop -a 

Output similar to the following should appear:

<num> workflow instances have been stopped 

The command will not return until all workflow execution instances have been stopped. No error messages should appear. 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 Workflow Execution Instance Options

To view options on all workflow execution instances, the omq.system.get-workflow-info() command must be sent to the API server. Execute the following command-line to send this command to the server:

unixprompt% ostatus -wv 

Output similar to the following should appear:

Qorus 4.0.3.p2_git psft-int-av2s329t-1 sessionid 340
workflows:
 W   23 RETIRE/1.0                NORMAL               42/ 6 itera...
        + option: provident-no-messages = 1
 W   24 TRANSFER-USIM/1.0         NORMAL                0/ 9 itera...
        + option: provident-no-message = 1
        + option: provident-no-messages = 1 

Information like the above will appear for each running workflow execution instance. No error messages should appear. If an error message appears, see the following section for causes.

Note
See Command-Line Programs for more information on system programs such as ostatus: Show System, Workflow, and Service Status.
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 Workflow Execution Instance Options

To set workflow execution instance options, the omq.system.set-workflow-option() command must be sent to the HTTP server. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-workflow-option <id> <option>=<value> 

Output similar to the following should appear:

options set on workflow with execution ID <id> 

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

Common Errors

Error: Invalid Workflow Option

Error Message:
ERROR: WORKFLOW-OPTION-ERROR: list: ("invalid option '<option>'") 
Explanation:
The option is not supported by this workflow.
Possible Cause Action to Take
Option name is incorrect Check the option name again and try the command again with the correct name.

Error: Invalid Workflow Execution Instance ID

Error Message:
ERROR: INVALID-WORKFLOW-ID: there is no workflow with execution ID 11 
Explanation:
The workflow execution instance ID given does not correspond to a running workflow execution instance.
Possible Cause Action to Take
Instance ID is incorrect Check the execution instance ID again and try the command again with the correct ID number.

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, the omq.system.retry-workflow-instance() API method must be called by sending an appropriately formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd retry-workflow-instance <id> 

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 ocmd, 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:
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: STATUS-ERROR: can't update status 'R' (RETRY) 
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" or "ASYNC-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, either the omq.system.skip-step() or the omq.system.skip-step-without-retry() 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", or "ASYNC-WAITING" status. Execute the following command-line to send the omq.system.skip-step() command to the server:

unixprompt% ocmd omq.system.skip-step <workflow_instanceid> <stepid> [<index>] 

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 ocmd, 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 omq.system.set-workflow-instance-error() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd set-workflow-instance-error <id> 

Output similar to the following should appear:

hash: (4 members)
  steps_updated : 1
  segments_updated : 1
  workflow_status : "ERROR"
  old_status : "RETRY" 

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

Note
For more information on Qorus programs like ocmd, 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" 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 omq.system.cancel-workflow-instance() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow order data instance ID as an argument. Execute the following command-line to send this command to the server:

unixprompt% ocmd omq.system.cancel-workflow-instance <id> 

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 ocmd, 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", and "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 and has a load script of example-workflow-1.1.qrf, then the following command will load the new version of the workflow into the database:

unixprompt% oload @example-workflow-1.1.qrf 

The exact output will depend on the objects being updated in the release file, however here is an example:

installing Qorus user code from: example-workflow-1.1.qrf
installing release files: done
executing release files
creating functions from user/EXAMPLE-WORKFLOW/example-v1.1p1.qfd
done executing release files
installation complete! 

Any workflows running will be load the new configuration of the workflow from the database and use it whenever the omq.system.reset-workflow() method is called, without having to shut down the running workflow execution instances and restart them. 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, such as the omq.system.service.info.getWorkflowOverview() and the omq.system.service.info.getWorkflowOverviewFromName() methods. The oview program provides a user-friendly command-line interface to these methods (among others).

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, such as the omq.system.service.info.getWorkflowStatus() and the omq.system.service.info.getOrderInfo() methods. The oview program provides a user-friendly command-line interface to these methods (among others).

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 omq.system.reset-workflow() API method must be called by sending an appropriately-formatted request to the Qorus HTTP server with the workflow’s name and optionally the version as parameters as follows (note that if the version argument is omitted, all versions of the named workflow will be reset):

unixprompt% ocmd reset-workflow <name> [version] 

Output similar to the following should appear:

workflow <name>/<version> has been deleted from the cache and will be reloaded on next reference 

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

Common Errors

Error: Invalid Workflow Option

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.

Notes are displayed in the user interface.

Working With Services

Call a System Service Method

Use the ocmd command to call a system service method. Using this command, parameters can also be easily passed to the service 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% ocmd omq.system.service.<name>.<method> [args] 

The command’s output is dependent on the service method being called. Here is the output for the omq.system.service.omqmap.reload() method:

OK 

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.


Call a User Service Method

Calling a user service is just like calling a system service, except the word "system" is replaced with "user" in the command line. If the service is not already loaded, then it is loaded and initialized before the method is called.

The syntax is as follows:

unixprompt% ocmd omq.user.service.<name>.<method> [args] 

The command’s output is dependent on the service method being called. Here is example output for a hypothetical user method that gives no output but returns success:

OK 

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

Common Errors

Error: No Such Service

Error Message:
ERROR: SERVICE-ERROR: user 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: user 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 System Service

To stop a system service, it must be deleted from the Qorus service cache by calling the omq.system.delete-service() API method with the service’s name as the only parameter as follows:

unixprompt% ocmd [omq.system.]delete-service <service> 

If the service is currently loaded, then it will be deleted. If it is running, it will be stopped before it’s deleted. 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 deleting 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.


Stop a User Service

Stopping a user service is very similar to stopping a system service. To stop a user service, call the omq.user.delete-service() API method with the service’s name as the only parameter as follows:

unixprompt% ocmd omq.user.delete-service <service> 

If the service is currently loaded, then it will be deleted. If it is running, it will be stopped before it’s deleted. 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 deleting 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: user 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.


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 @service-release-1.1.qrf
...
unixprompt% ocmd omq.user.reset-service service
OK 

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 omq.system.add-user() API method as follows.

unixprompt% ocmd add-user <name> <pw> "<desc>" <role(s)...> 

For example:

unixprompt% ocmd add-user fred mypass123 "Fred Smith" 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 omq.system.update-user() API method as follows (at least one of the hash options must be given):

unixprompt% ocmd update-user <username> [pass=<pass>,name=<name>,roles=<role,...>] 

For example:

unixprompt% ocmd update-user fred name="Fred 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. 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 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:
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
To add or delete roles from a user, call "user-tool -R" (to add roles), or "user-tool -O" (to delete roles).

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 omq.system.update-current-user() API method as follows:

unixprompt% ocmd update-current-user pass=<new_pass> 

For example:

unixprompt% ocmd update-current-user fred 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 omq.system.delete-user() API method as follows:

unixprompt% ocmd delete-user <name> 

For example:

unixprompt% ocmd delete-user 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 roles) 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
  * (PERMISSION) SYSTEM: EXEC-SYNC-WORKFLOW
  * (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: SENSITIVE-DATA-CONTROL
  * (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 omq.system.add-role() API method as follows:

unixprompt% ocmd add-role <name> "<desc>" <permissions> 

For example:

unixprompt% ocmd add-role operator2 "Limited Operator" LOGIN,CALL-SYSTEM-SERVICES-RO,CALL-USER-SERVICES-RO,OPTION-CONTROL 

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:
ERROR: 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:
ERROR: 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>...] 

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 omq.system.update-role() API method as follows (note that permissions can be relative; ex: +LOGIN,-OPTION-CONTROL):

unixprompt% ocmd update-role <name> [desc=<desc>,permissions=<permission,...>,groups=<group,...>] 

For example:

unixprompt% ocmd update-role operator2 "New Operator Role" -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 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 omq.system.delete-role() API method as follows:

unixprompt% ocmd delete-role <name> 

For example:

unixprompt% ocmd delete-role 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:
ERROR: 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 omq.system.add-permission() API method as follows:

unixprompt% ocmd add-permission <name> "<description>" 

For example:

unixprompt% ocmd add-permission USER-PERMISSION-1 "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 omq.system.update-permission() API method as follows:

unixprompt% ocmd update-permission <name> <description> 

For example:

unixprompt% ocmd update-permission USER-PERMISSION-1 "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 omq.system.delete-permission() API method as follows:

unixprompt% ocmd delete-permission <name> 

For example:

unixprompt% ocmd delete-permission 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 with a validity period of 365 days and without a password for the private key is as follows:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes 

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?action=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 process. 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

Error: Environment Error

Error Message:
unhandled QORE System exception thrown in TID 1 at ../ocmd:11
PARSE-EXCEPTION: cannot open include file "qorus-client.ql" 
Explanation:
The program could not find the include file "qorus-client.ql" and therefore cannot execute.
Possible Cause Action to Take
The $QORE_INCLUDE_DIR environment variable is not configured properly Check the $QORE_INCLUDE_DIR environment variable, it must be set to $OMQ_DIR/qlib
The Qorus installation is corrupt; $OMQ_DIR/qlib is missing or empty Check your $OMQ_DIR environment variable and the filesystem, reinstall from the original installation package if necessary to restore system files.