Qorus Integration Engine®  4.0.3.p1_git
Connections and Connection Monitoring

Introduction to Connections

Qorus supports automatic connection monitoring and dependent interface management based on connection status. The following connection types are monitored:

Note
Automatic interface management can be disabled by setting system option qorus.manage-interfaces to False; in this case interfaces are not started and stopped automatically based on their connection status

All connections are defined in the database (in the CONNECTIONS table) and are usually created as a part of a user release, but can also be created via REST API calls (ex: POST /api/latest/remote/user).

Qorus to Qorus Connections

These connection definitions can be used in user code (workflow, service, and job code) by using one of the following APIs:

See also
GET /api/latest/remote/qorus for information about manipulating remote Qorus to Qorus connections via the REST API
Note
The "qorus" connection name is provided by default by the QorusConnectionProvider module as a connnection to the local Qorus instance, therefore it's recommended not to use "qorus" for a user or remote connection name

Remote Connection Types

Scheme Object Description
"qorus" OMQ::QorusSystemRestHelper unencrypted Qorus HTTP connections
"qoruss" OMQ::QorusSystemRestHelper encrypted Qorus HTTPS connections

Remote Connection Keys

Key Mandatory? Description Example
url Y full URL to remote instance http://user:pass@localhost:8001
desc N public description of the connection production server 2
proxy N full URL to proxy used for remote instance http://proxy.mydomain.com
connect_timeout N Initial connection timeout in seconds 10
timeout N Timeout for regular user calls in seconds 30
api_version N The REST API version for REST connections; default: "latest" v2
ignore_socket_warnings N If true then socket I/O warnings will not be issued for the given remote connection true
Note
All attributes of remote connection defintions are subject to environment variable substitution
See also
Connection File Parsing

Deployment (qconn) File Example

foo = ( desc=remote Qorus instance, url = http://localhost:8001, timeout=30 )
bar = (
  desc=remote Qorus instance,
  url=http://user:pass@localhost:8001,
  proxy=http://proxy.local,
  conn_timeout=10,
  timeout=30
)
See also

User Connections

User connections are acquired in user code by the following API:

User connections can be disabled and enabled by an operator (or authenticated user). The functionality is covered by /api/remote/user

User connection objects are of the type defined by the connection; the connection URLs and connection objects in the following table are supported by Qorus (see qorus.connection-modules for an option allowing for user-defined connection types).

User Connection Types

Scheme Object Documentation
awsrests AwsRestClient AWS REST User Connections
file, dir Dir Filesystem/Directory User Connections
ftp, ftps FtpClient FTP User Connections
http, https HTTPClient HTTP User Connections
jsonrpc, jsonrpcs JsonRpcClient JSON-RPC User Connections
pop3, pop3s Pop3Client POP3 User Connections
rest, rests RestClient REST User Connections
sewiorest, sewiorests SewioRestClient Sewio.net RTLS Studio REST API User Connections
sewiows, sewiowss SewioWebSocketConnection Sewio WebSocket User Connections
sftp SFTPClient SFTP Connections
sfrests SalesforceRestClient Salesforce.com REST User Connections
smtp, smtps, smtptls,
esmtp, esmtptls
SmtpClient SMTP Connections
soap, soaps SoapClient SOAP Connections
telnet TelnetClient TELNET User Connections
ws, wss WebSocketClient WebSocket User Connections
xmlrpc, xmlrpcs XmlRpcClient XML-RPC User Connections
yamlrpc, yamlrpcs YamlRpcClient YAML-RPC User Connections
zeyosrest, zeyosrests ZeyosRestClient Zeyos.com REST API User Connections
See also
Note
The "qorus" connection name is provided by default by the QorusConnectionProvider module as a connnection to the local Qorus instance, therefore it's recommended not to use "qorus" for a user or remote connection name

AWS REST User Connections

Description
get_user_connection() returns a AwsRestClient object; socket performance is monitored.
Example
awsrest-connection = (
    desc = My AWS REST HTTP connection,
    url = awsrests://iotevents.eu-central-1.amazonaws.com,
    client_id = V9HjEFLihcwfAbxAJUvxzifnE7uwuNFoEYjNoK5kxI1GubH1Cc9khkXNHBIQ6ljbJGRw1PRxIe2CI9K3rBZQF,
    client_secret = JrL7TeubWmQwxUb5Ry5,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"sfrests" encrypted Salesforce.com REST HTTP connections
Connection Options
Option Description
"api" the Salesforce.com API to use; use "auto" (the default) to use the latest API version
"aws_keyid" (required) the AWS key ID
"aws_region" the AWS region to use (ex: "us-east-1"); if it cannot be derived from the URL then it is a required option
"was_service" the AWS service to use (ex: "iam"); if it cannot be derived from the URL then it is a required option
"aws_secret" (required) the AWS secret access key value
"aws_token" a temporary session token from AWS Security Token Service for this HTTP session
"aws_s3" set to True to flag this object for use with AWS aws_s3, which requires special message encoding
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"error_passthru" if True then HTTP status codes indicating errors will not cause an REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers" an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"timeout" transfer timeout to use in milliseconds
See also
  • AwsRestClient::AwsRestConnection
  • AwsRestClient::constructor() for more information on the above options

Filesystem/Directory User Connections

Description
get_user_connection() returns a Dir object giving a location on the local system's filesystem; monitoring monitors for free space.
Example
file-connection = (
    desc = filesystem connection,
    url = file://$SOME_DIRECTORY/input
)
Schemes
URI Scheme Description
"dir" filesystem connection
"file" filesystem connection
See also
ConnectionProvider::FilesystemConnection

FTP User Connections

Description
get_user_connection() returns an FtpClient object; socket performance is monitored.
Example
ftp-connection = (
    desc = HTTP connection,
    url = ftp://user:pass@example.com:8080/path
)
Schemes
URI Scheme Description
"ftp" FTP connections; default control port 21 if not present in the URL
"ftps" FTPS connections; secure FTP (not SFTP); default control port 21 if not present in the URL
See also

HTTP User Connections

Description
get_user_connection() returns an HTTPClient object; socket performance is monitored.
Example
http-connection = (
    desc = My HTTP connection,
    url = https://user:pass@example.com:8080/path,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"http" non-encrypted HTTP connections; default port 80 if not present in the URL
"https" encrypted HTTPS connections; default port 443 if not present in the URL
Connection Options
Option Description
"connect_timeout" connection timeout to use in milliseconds
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
See also

JSON-RPC User Connections

Description
get_user_connection() returns a JsonRpcClient object; socket performance is monitored.
Example
jsonrpc-connection = (
    desc = My JSON-RPC HTTP connection,
    url = jsonrpcs://user:pass@example.com:8080/path,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"jsonrpc" non-encrypted JSON-RPC HTTP connections; default port 80 if not present in the URL
"jsonrpcs" encrypted JSON-RPC HTTPS connections; default port 443 if not present in the URL
Options
Option Description
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
"connect_timeout" connection timeout to use in milliseconds
See also

POP3 User Connections

Description
get_user_connection() returns a Pop3Client object; socket performance is monitored.
Example
pop3-connection = (
    desc = My POP3 Connection,
    url = pop3s://username@example.com:password@pop.gmail.com,
)
Schemes
URI Scheme Description
"pop3" non-encrypted POP3 connections; default port 110 if not present in the URL
"pop3s" encrypted POP3 connections; default port 995 if not present in the URL
Runtime Connection Options
Option Description
"log" a closure accepting a single string for logging
"dbglog" a closure taking a single string for detailed technical connection logging
See also
Pop3Client::Pop3Connection

REST User Connections

Description
get_user_connection() returns a RestClient object; socket performance is monitored.
Example
rest-connection = (
    desc = My REST HTTP connection,
    url = rests://user:pass@example.com:8080/path,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"rest" non-encrypted REST HTTP connections; default port 80 if not present in the URL
"rests" encrypted REST HTTPS connections; default port 443 if not present in the URL
Connection Options
Option Description
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data" see DataSerializationOptions for possible values; the default is "auto"; note that it's recommended to use "yaml" when talking to Qorus
"error_passthru" if True then HTTP status codes indicating errors will not cause an REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers" an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"timeout" transfer timeout to use in milliseconds
See also

Sewio.net RTLS Studio REST API User Connections

Description
get_user_connection() returns a SewioRestClient object; socket performance is monitored.
Example
sewiorest-connection = (
    desc = My Sewio.net RTLS Studio REST HTTP connection,
    url = sewiorest://rtlsstudio.com/sensmapserver,
    apikey = JrL7TeubWmQwxUb5Ry5,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"sewiorest" unencrypted Sewio.net RTLS Studio REST HTTP connections
"sewiorests" encrypted Sewio.net RTLS Studio REST HTTPS connections
Connection Options
Option Description
"apikey" (required) the Sewio.net API key
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data" see DataSerializationOptions for possible values; the default is "json"
"error_passthru" if True then HTTP status codes indicating errors will not cause an REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers" an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 3.1.1

Sewio WebSocket User Connections

Description
get_user_connection() returns a SewioWebSocketClient object; socket performance is monitored.
Example
sewiows-connection = (
    desc = My Sewio WebSocket Connection,
    url = sewiows://rtlsstudio.com:8080,
    apikey = JrL7TeubWmQwxUb5Ry5,
)
Schemes
URI Scheme Description
"sewiows" non-encrypted Sewio WebSocket connections; default port 80 if not present in the URL
"sewiowss" TLS/SSL encrypted Sewio WebSocket connections; default port 443 if not present in the URL
Options
Option Description
"apikey" (required) Sewio API key
"connect_timeout" connection timeout to use in milliseconds
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
Runtime Connection Options
Option Description
"callback" (required) a callback for websocket events
"dbglog" a closure taking a single string for detailed technical connection logging
"errlog" a closure taking a single string for error logging
"log" a closure accepting a single string for logging
See also
Since
Qorus 3.1.1

Salesforce.com REST User Connections

Description
get_user_connection() returns a SalesforceRestClient object; socket performance is monitored.
Example
sfrest-connection = (
    desc = My Salesforce.com REST HTTP connection,
    url = sfrests://user:password@login.salesforce.com/services/oauth2/token,
    client_id = V9HjEFLihcwfAbxAJUvxzifnE7uwuNFoEYjNoK5kxI1GubH1Cc9khkXNHBIQ6ljbJGRw1PRxIe2CI9K3rBZQF,
    client_secret = JrL7TeubWmQwxUb5Ry5,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"sfrests" encrypted Salesforce.com REST HTTP connections
Connection Options
Option Description
"api" the Salesforce.com API to use; use "auto" (the default) to use the latest API version
"client_id" (required) the Salesforce.com "consumer key" for the Connected App
"client_secret" (required) the Salesforce.com "consumer secret" for the Connected App
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data" see DataSerializationOptions for possible values; the default is "auto"
"error_passthru" if True then HTTP status codes indicating errors will not cause an REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers" an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"timeout" transfer timeout to use in milliseconds
See also

SFTP Connections

Description
get_user_connection() returns a SFTPClient object; socket performance is monitored.
Example
sftp-connection = (
    desc = My SFTP Connection,
    url = sftp://username:password@sftp.example.com,
)
Schemes
URI Scheme Description
"sftp" SFTP connections; default port 22 if not present in the URL
Options
Option Description
"keyfile" a path to the private key file for key-based authentication
Runtime Connection Options
Option Description
"path" overrides the path component in the URL at runtime
"path_add" appends the given string to the path component of the URL at runtime
See also
Ssh2Connections::SftpConnection

SMTP Connections

Description
get_user_connection() returns a SmtpClient object; socket performance is monitored.
Example
smtp-connection = (
    desc = My SMTP Connection,
    url = esmtptls://username:password@smtp.example.com,
)
Schemes
URI Scheme Description
"smtp" standard SMTP port (25) without encryption; ESMPT and "STARTTLS" detection is supported automatically
"smtps" SMTP on port 465 without encryption; ESMPT and "STARTTLS" detection is supported automatically
"smtptls" standard SMTP port (25); a "STARTTLS" command is executed unconditionally after the connection
"esmtp" SMTP on port 587 without encryption; ESMPT and "STARTTLS" detection is supported automatically
"esmtptls" SMTP on port 587; a "STARTTLS" command is executed unconditionally after the connection
Runtime Connection Options
Option Description
"log" a closure accepting a single string for logging
"dbglog" a closure taking a single string for detailed technical connection logging
See also
SmtpClient::SmtpConnection

SOAP Connections

Description
get_user_connection() returns a SoapClient object; socket performance is monitored.
Example
soap-connection = (
    desc = My SOAP Connection,
    url = soap://ignored-see-wsdl-option,
    wsdl = file:///$OMQ_DIR/user/wsdl/my-soap.wsdl,
)
Schemes
URI Scheme Description
"soap" SOAP connections; the URL here will be used to retrieve the WSDL using HTTP; use the "wsdl" option to override (for example, to retrieve the WSDL from a file)
"soaps" SOAP connections; the URL here will be used to retrieve the WSDL using HTTPS; use the "wsdl" option to override (for example, to retrieve the WSDL from a file)
Options
Option Description
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"connect_timeout" connection timeout to use in milliseconds
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"port" in case multiple port entries are found in the WSDL, give the one to be used here
"portType" in case multiple portType entries are found in the WSDL, give the one to be used here
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"target_url" overrides the URL in the WSDL (mapped to "url" in the SoapClient constructor argument)
"timeout" transfer timeout to use in milliseconds
"wsdl" overrides the WSDL to use for the connection; "wsdl" values with a "file://" scheme are subject to environment variable substitution
See also

TELNET User Connections

Description
get_user_connection() returns a TelnetClient object; socket performance is monitored.
Example
telnet-connection = (
    desc = My TELNET Connection,
    url = telnet://username@example.com:password@example.com,
)
Schemes
URI Scheme Description
"telnet" standard TELNET connections; default port 23 if not present in the URL
Runtime Connection Options
Option Description
"log" a closure accepting a single string for logging
"dbglog" a closure taking a single string for detailed technical connection logging
See also
TelnetClient::TelnetConnection

WebSocket User Connections

Description
get_user_connection() returns a WebSocketClient object; socket performance is monitored.
Example
ws-connection = (
    desc = My WebSocket Connection,
    url = ws://username:example.com:password@example.com,
)
Schemes
URI Scheme Description
"ws" non-encrypted WebSocket connections; default port 80 if not present in the URL
"wss" encrypted WebSocket connections; default port 443 if not present in the URL
Options
Option Description
"connect_timeout" connection timeout to use in milliseconds
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
Runtime Connection Options
Option Description
"callback" (required) a callback for websocket events
"dbglog" a closure taking a single string for detailed technical connection logging
"errlog" a closure taking a single string for error logging
"log" a closure accepting a single string for logging
See also

XML-RPC User Connections

Description
get_user_connection() returns a XmlRpcClient object; socket performance is monitored.
Example
xmlrpc-connection = (
    desc = My XML-RPC HTTP connection,
    url = xmlrpcs://user:pass@example.com:8080/path,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"xmlrpc" non-encrypted XML-RPC HTTP connections; default port 80 if not present in the URL
"xmlrpcs" encrypted XML-RPC HTTPS connections; default port 443 if not present in the URL
Options
Option Description
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
"connect_timeout" connection timeout to use in milliseconds
See also

YAML-RPC User Connections

Description
get_user_connection() returns a YamlRpcClient object; socket performance is monitored.
Example
yamlrpc-connection = (
    desc = My YAML-RPC HTTP connection,
    url = yamlrpcs://user:pass@example.com:8080/path,
    timeout = 60000,
    connect_timeout = 30000,
)
Schemes
URI Scheme Description
"yamlrpc" non-encrypted YAML-RPC HTTP connections; default port 80 if not present in the URL
"yamlrpcs" encrypted YAML-RPC HTTPS connections; default port 443 if not present in the URL
Options
Option Description
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"timeout" transfer timeout to use in milliseconds
"connect_timeout" connection timeout to use in milliseconds
See also

Zeyos.com REST API User Connections

Description
get_user_connection() returns a ZeyosRestClient object; socket performance is monitored.
Example
zeyosrest-connection = (
    desc = My Zeyos.com REST HTTP connection,
    url = zeyosrest://cloud.zeyos.com/test,
    token = 66f258ca62439adad2bf593f908032e255e125ed,
)
Schemes
URI Scheme Description
"zeyosrest" unencrypted Zeyos.com REST HTTP connections
"zeyosrests" encrypted Zeyos.com REST HTTPS connections
Connection Options
Option Description
"name" (mandatory) the zeyos.com's name
"password" (mandatory) the zeyos.com's password
"identifier" (mandatory) the zeyos.com's identifier
"appsecret" (mandatory) the zeyos.com's appsecret
"token" the zeyos.com's token, if provided then name, password, identifier and appsecret are not needed and will be ignored.
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data" see RestClient::RestClient::DataSerializationOptions for possible values when used with the null REST schema validator; the default is "auto"
"error_passthru" if True then HTTP status codes indicating errors will not cause an REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers" an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"swagger" the path to a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module)
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 4.0.1

SalesforceSoapConnection User Connection Module

Description
The SalesforceSoapConnection module can be used to provide access to Salesforce.com user connections in Qorus by returning SalesforceSoapClient objects to Qorus user code on demand.

To use this module; add "SalesforceSoapConnection" to the qorus.connection-modules system option in the options file as follows:
qorus.connection-modules: SalesforceSoapConnection
Example
salesforce-crm = (
    desc = Salesforce.com CRM SOAP Connection,
    url = sfsoap://ignored-see-wsdl-option,
    wsdl = file:///$OMQ_DIR/user/wsdl/enterprise.wsdl,
    username = username@example.com,
    password = my_password,
    token = aJCabsJnXVtVxjWnjyyLNY1L
)
Schemes
URI Scheme Description
"sfsoap" Salesforce.com SOAP HTTP connections; the URL here is used to retrieve the WSDL using HTTP; use the "wsdl" option to override (for example, to retrieve the WSDL from a file)
"sfsoaps" Salesforce.com SOAP HTTP connections; the URL here is used to retrieve the WSDL using HTTPS; use the "wsdl" option to override (for example, to retrieve the WSDL from a file)
Connection Options
Option Description
"connect_timeout" connection timeout to use in milliseconds
"content_encoding" this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"http_version" HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects" maximum redirects to support
"password" (required) the Salesforce.com password to use for the connection; can be specified using system properties instead (see below)
"port" in case multiple port entries are found in the WSDL, give the one to be used here
"portType" in case multiple portType entries are found in the WSDL, give the one to be used here
"proxy" proxy URL to use
"send_encoding" a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"target_url" overrides the URL in the WSDL (mapped to "url" in the SalesforceSoapClient constructor argument)
"timeout" transfer timeout to use in milliseconds
"token" (required) the Salesforce.com user API token to use for the connection; can be specified using system properties instead (see below)
"username" (required) the Salesforce.com username to use for the connection; can be specified using system properties instead (see below)
"wsdl" overrides the WSDL to use for the connection; "wsdl" values with a "file://" scheme are subject to environment variable substitution
Runtime Connection Options
Option Description
"log" a closure accepting a single string for logging
"dbglog" a closure taking a single string for detailed technical connection logging
Note
that the following options can be specified with system properties by providing a value for each of the following keys in the "salesforce.com" system property domain:
  • "password"
  • "token"
  • "username"
In this case, the above authentication options do not have to be present in the connection file itself
See also
SalesforceSoapClient::constructor(hash opts) for more information on the above options

TibcoActiveEnterprise User Connection Module

Customers with valid TIBCO ActiveEnterprise (TM) licenses (must be purchased separately from TIBCO, Inc) can use the TibcoActiveEnterprise module to provide Qorus user connections to TIBCO ActiveEnterprise adapters.

The connection scheme is "tibae"; the URL is in the format:

  • tibae://rvSessionName

To use this module; add "TibcoActiveEnterprise" to the qorus.connection-modules system option in the options file as follows:

qorus.connection-modules: TibcoActiveEnterprise

This user connection supports the following options:

Option Required Description
"properties" Y adapter properties in the following format: key1=value1;key2=value2;...
"ping" Y a service and method name for monitoring in the following format: "service.method"; the method must take a single TibcoAdapter argument; any errors in the ping should be thrown as exceptions
"classes" N an optional list of class locations in the following format: class1=path1;class2=path2;...

The following is an example connection file:

tibae-test = (
  url = tibae://rvSession,
  desc = TIBCO ActiveEnterprise Adapter monitoring test,
  ping = tibae-test.ping,
  properties = AppVersion=1.0;AppInfo=test;AppName=testAdapter;RepoURL=$OMQ_DIR/user/adapters/new.dat;ConfigURL=/tibco/private/adapter/testAdapter,
  classes = Test=/tibco/public/class/ae/Test
)

The following is an example service implementing the ping method:

# -*- mode: qore; indent-tabs-mode: nil -*-
# service: tibae-test
# serviceversion: 1.0
# servicedesc: tibae monitoring test service
# serviceauthor: Qore Technologies, sro
# define-group: test: test interfaces
# groups: test
# ENDSERVICE
# name: init
# desc: initializes the service
%new-style
%requires tibae
const Subject = "QORE.Test.QORETest";
const MsgOut = (
"STRING" : "hello there",
);
const test_class = "/tibco/public/class/ae/Test";
sub init() {
}
# END
# desc: pings the remote end
%new-style
sub ping(TibcoAdapter adapter = get_user_connection("tibae-test")) {
*hash h = adapter.sendSubjectWithSyncReply(Subject + ".1", test_class, MsgOut, 10s);
if (!h)
throw "TIBAE-TIMEOUT", "message to remote adapter timed out";
log(LL_INFO, "got ping response: %y", h);
}
# END

Datasource Connections

Datasources are system-wide named connections to external databases. Qorus datasources are defined in the Qorus system DB schema; from these definitions datasource connections can be acquired in the following ways:

Database connections are using special URI with a form db://driver:user/pass@database[(encoding)][host][:port][{min=#,max=#,coord-mode}]

Note that db:// prefix, driver, and database are always required. driver must be a valid Qore database driver name. min and max give the minimum and maximum connections for DatasourcePool objects based on that connection string, respectively. See Datasource Connection Pools and the qdsp Mode for a description of the coord_mode option

The encoding specification describes the character set encoding to be used when communicating with the database server and must be made in the format required by the database driver (i.e. "AL32UTF8" for UTF-8 with an Oracle driver).

For example:

db://oracle:qorususer/qorususer@qorusdb

Remote Connection Types

Scheme Object Description
db Datasource or DatasourcePool; or referenced by the common parent class AbstractDatasource a DB/SQL access object
See also

Datasource Connection Pools and the qdsp Mode

When a connection pool object is aqcuired, an object is returned that is an injected client for qdsp processes; how this object acquires a connection and executes SQL depends on the qdsp mode option for the given datasource.

To enable coordinated mode for a given datasource, the "coord-mode" option can be set in the datasource URL as in the following example:

db://driver:user/password@dbname{coord-mode}

which is equivalent to:

db://driver:user/password@dbname{coord-mode=true}

Coordinated mode can also be disabled for a given datasource (in case it has been enabled by default with the default-datasource-coordinated option) by setting the coord-mode option to false as in the following example:

db://driver:user/password@dbname{coord-mode=false}
Note
  • Any value provided ot the coord-mode option is parsed with parse_boolean()
  • Setting the coord-mode option in the datasource URL overrides any default-datasource-coordinated option and therefore can be used to ensure that the desired coord-mode value is used for the datasource in all cases.
  • The coord-mode option is only used by Qorus; it is not passed to the database driver
See also
qdsp Datasource Resets

Connection File Parsing

Connection File Parsing and Special Character Handling

Connection files are parsed as free-form text where whitespace is generally ignored.

The following characters are special in connection files, and can only be used literally when included in quoted strings:

  • ": indicates the start of a quoted string
  • ,: separates option declarations of a connection
  • (: indicates the beginning of option declarations of a connection
  • ): indicates the end of option declarations of a connection
  • $: indicates that environment variable substitution should be performed
Note
  • literal CR ("\r") characters are ignored in connection files; to include a CR character in an attribute, use it in a quoted string as described below
  • quotes (") and parentheses (( and )) can also be used in unquoted strings with leading alphabetic characters for backwards-compatibility with previous versions of Qorus

Quoted strings must be delimited with "; for forward compatibility, it's best to delimit any strings with special characters listed above with ".

Quoted strings accept escape characters; any character may be escaped by prefacing the character with a "\" character, however the following escape characters have special values in connection files when escaped:

  • "\n": indicates a newline (ASCII 10)
  • "\r": indicates a carriage return (ASCII 13)
  • "\t": indicates a tab (ASCII 9)

To use one of the special characters listed above, use the character in a quoted string and escape it as in the following example:

https-remote-1 = (
    desc = remote HTTPS connection,
    url = "https://user:'pass'\$\"word\"@example.com:11098",
)

Connection File Environment Variable Substitution

All attributes of connection files (remote and user connection files) are subject to environment variable substitution. Any text with the following format will be substituted with the value of the given environment variable:

  • $VAR
  • ${VAR}

For example, in the following file:

fs-staging = (
    desc = Staging filesystem connection,
    url = file://$DIR_ROOT/staging,
)

Assuming that the $DIR_ROOT environment variable is assigned to /project/qorus, then the value of the url option would be set to file:///project/qorus/staging.

To prohibit environment variable substitution and use a literal "$" character in a URL (for example, as a character in a password value in a URL), enclose the string in single or double quotes and place a backslash character before the "$" sign as follows:

https-remote-1 = (
    desc = remote HTTPS connection,
    url = "https://user:pass\$word@example.com:11098",
)

In this way the url option would be set to https://user:pass$word@example.com:11098. Due to environment variable substitution, "$" characters are special characters that must be escaped as in the above examples in quoted strings in connection files to be used literally.

Connection Monitoring

Monitoring Overview

Connections are monitored regularly by executing their "ping" methods, which make a small round trip call to the remote endpoint. If there is an error establishing the connection or receiving the response, then the connection is marked as down.

When a connection is marked as down, an ongoing alert is raised, and any dependent interfaces are also stopped (see Connection Dependencies). The associated ongoing alert is raised again when the connection is monitored to be up again.

Note
Manually called ping methods will also affect monitored connection status (a successfull ping will mark a "down" interface as up and vice versa).

Connection Dependencies

Once any workflow, service, or job requests a connection (assuming that any register_dependency argument is True), the connection is then automatically registered as a dependency of the interface object, so that if the connection is monitored to go down, the dependent interface object will be stopped. When connection monitoring determines that the connection is back up, the dependent interfaces are restarted (for workflows and services this also depends on their autostart setting).