Qorus Integration Engine®  5.1.15_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
  • Loopback connections should always use one of "::" "127.0.0.1", or "localhost" as the target host name in the URL in order to be recognized as loopback connections

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

Deployment (qconn) File Example

# This is a generated file, don't edit!
type: connection
name: my-qorus-1
desc: My Remote Qorus Instance
url: qorus://example.com:8001
options:
    timeout:
        type: int
        value: 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
billwerkrest, billwerkrests BillwerkRestClient billwerk.com REST API User Connections
cdsrests CdsRestClient Microsoft Dynamics 365 / Common Data Service 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
sap4hanarests Sap4HanaRestClient SAP S/4Hana REST API 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
snrests ServiceNowRestClient ServiceNow REST User 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
UserApi::getUserConnection() returns a AwsRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: awsrest-connection
desc: My AWS REST HTTP connection
url: awsrests://iotevents.eu-central-1.amazonaws.com
options:
    client_id:
        type: string
        value: V9HjEFLihcwfAbxAJUvxzifnE7uwuNFoEYjNoK5kxI1GubH1Cc9khkXNHBIQ6ljbJGRw1PRxIe2CI9K3rBZQF
    client_secret:
        type: string
        value: JrL7TeubWmQwxUb5Ry5
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
"aws_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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also

billwerk.com REST API User Connections

Description
UserApi::getUserConnection() returns a BillwerkRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: billwerkrests-connection
desc: My billwerk.com REST HTTP connection
url: billwerkrests://api.billwerk.com
options:
    client_id:
        type: string
        value: _id_
    client_secret:
        type: string
        value: _secret_
    swagger:
        type: string
        value: "https://developer.billwerk.io/swagger.json"
Schemes
URI Scheme Description
"billwerkrest" unencrypted billwerk.com REST HTTP connections
"billwerkrests" encrypted billwerk.com REST HTTPS connections
Connection Options
Option Description
"name" (optional*) the billwerk.com username; required if client_secret is not provided
"password" (optional*) the billwerk.com user password; required if client_secret is not provided
"client_id" (mandatory) the billwerk.com client ID
"client_secret" (optional*) the billwerk.com client secret; required if username and password are not provided
"token" the billwerk.com token, if provided then name, password, client_id and client_secret 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 "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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 4.1.2

Microsoft Dynamics 365 / Common Data Service REST User Connections

Description
UserApi::getUserConnection() returns a CdsRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: My Dynamics 365 Connection
desc: test
url: cdsrests://qt-dev.crm4.dynamics.com
options:
    client_id:
        type: string
        value: fba80400-68e9-43dd-8cf2-fe163b730365
    client_secret:
        type: string
        value: "DkIMz?!NW(aHOkb'5>GF328-no*')xbU"
    tenant:
        type: string
        value: d630b231-ae5a-411a-b9d5-0f70af81f034
Schemes
URI Scheme Description
"cdsrests" encrypted Microsoft Dynamics 365 / Common Data Service REST HTTP connections
Connection Options
Option Description
"api" the CDS API level to use; if not present, the default API level for the CdsRestClient object is used
"client_id" (required) the CDS client ID
"client_secret" (required) the CDS client secret
"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
"scope" the scope to use when logging in; the default is to use the URL + "/.default"
"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 location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"tenant" (required) the tenant ID to use
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 5.0

Filesystem/Directory User Connections

Description
UserApi::getUserConnection() returns a Dir object giving a location on the local system's filesystem; monitoring monitors for free space.
Example
# This is a generated file, don't edit!
type: connection
name: 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
UserApi::getUserConnection() returns an FtpClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: ftp-connection
desc: My FTP 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
UserApi::getUserConnection() returns an HTTPClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: http-connection
desc: My HTTP connection
url: https://user:pass@example.com:8080/path
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
UserApi::getUserConnection() returns a JsonRpcClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: jsonrpc-connection
desc: My JSON-RPC connection
url: jsonrpcs://user:pass@example.com:8080/path
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
UserApi::getUserConnection() returns a Pop3Client object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: 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
UserApi::getUserConnection() returns a RestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: rest-connection
desc: My REST HTTP connection
url: rests://user:pass@example.com:8080/path
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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also

SAP S/4Hana REST API User Connections

Description
UserApi::getUserConnection() returns a Sap4HanaRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-sap-connection
desc: My SAP S/4Hana REST HTTPS connection
url: sap4hanarests://https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap
options:
    apikey:
        type: string
        value: V3EC5RWfWTTn9Gl5xWTVwevWHCT1vusdG
Schemes
URI Scheme Description
"sap4hanarests" encrypted SAP S/4Hana REST HTTPS connections
Connection Options
Option Description
"apikey" (required) the SAP S/4Hana 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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 4.0.3.p2

Sewio.net RTLS Studio REST API User Connections

Description
UserApi::getUserConnection() returns a SewioRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-sewiorest-connection
desc: My Sewio.net RTLS Studio REST HTTPS connection
url: sewiorest://rtlsstudio.com/sensmapserver
options:
    apikey:
        type: string
        value: JrL7TeubWmQwxUb5Ry5
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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also
Since
Qorus 3.1.1

Sewio WebSocket User Connections

Description
UserApi::getUserConnection() returns a SewioWebSocketClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-sewiows-connection
desc: My Sewio.net RTLS Studio WebSocket connection
url: sewiows://rtlsstudio.com:8080
options:
    apikey:
        type: string
        value: 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
UserApi::getUserConnection() returns a SalesforceRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-sfrest-connection
desc: My Salesforce.com REST HTTP connection
url: sfrests://user:password@login.salesforce.com/services/oauth2/token
options:
    client_id:
        type: string
        value: V9HjEFLihcwfAbxAJUvxzifnE7uwuNFoEYjNoK5kxI1GubH1Cc9khkXNHBIQ6ljbJGRw1PRxIe2CI9K3rBZQF
    client_secret:
        type: string
        value: JrL7TeubWmQwxUb5Ry5
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 "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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
See also

SFTP Connections

Description
UserApi::getUserConnection() returns a SFTPClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-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
UserApi::getUserConnection() returns a SmtpClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-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

ServiceNow REST User Connections

Description
UserApi::getUserConnection() returns a ServiceNowRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: My ServiceNow Connection
desc: test
url: snrests://dev493922.service-now.com
options:
    client_id:
        type: string
        value: b73a867187eb18f62d89820395417684
    client_secret:
        type: string
        value: "M09tfOc&NoEP(XCEKkT:T&V<lKR%+=h9hw"
    username:
        type: string
        value: admin
    password:
        type: string
        value: mypassword
Schemes
URI Scheme Description
"snrests" encrypted ServiceNow REST HTTP connections
Connection Options
Option Description
"api" the API level to use; if not present, the default API level for the ServiceNowRestClient object is used
"client_id" (required) the OAuth2 client ID
"client_secret" (required) the OAuth2 client secret
"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
"password" (required) the ServiceNow password to use
"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 location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"timeout" transfer timeout to use in milliseconds
"username" (required) the ServiceNow username to use
See also
Since
Qorus 5.0.5

SOAP Connections

Description
UserApi::getUserConnection() returns a SoapClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-soap-connection
desc: My SOAP connection
url: soaps://example.com/service1?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" the location of the WSDL for the connection; overrides the URL; ex: resource://service-name:my-wsdl.xml
See also

TELNET User Connections

Description
UserApi::getUserConnection() returns a TelnetClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-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
UserApi::getUserConnection() returns a WebSocketClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-ws-connection
desc: My WebSocket connection
url: wss://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
UserApi::getUserConnection() returns a XmlRpcClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: xmlrpc-connection
desc: My XML-RPC connection
url: xmlrpcs://user:pass@example.com:8080/path
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
UserApi::getUserConnection() returns a YamlRpcClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: yamlrpc-connection
desc: My YAML-RPC connection
url: yamlrpcs://user:pass@example.com:8080/path
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
UserApi::getUserConnection() returns a ZeyosRestClient object; socket performance is monitored.
Example
# This is a generated file, don't edit!
type: connection
name: my-zeyosrest-connection
desc: My Zeyos.com REST HTTP connection
url: zeyosrest://cloud.zeyos.com/test
options:
    token:
        type: string
        value: 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 name
"password" (mandatory) the zeyos.com password
"identifier" (mandatory) the zeyos.com identifier
"appsecret" (mandatory) the zeyos.com appsecret
"token" the zeyos.com 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 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
"swagger" the location of a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); ex: resource://service-name:swagger-resource.yaml
"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
# This is a generated file, don't edit!
type: connection
name: my-sfsoap-connection
desc: My Salesforce.com CRM SOAP connection
url: sfsoap://ignored-see-wsdl-option
options:
    wsdl:
        type: string
        value: "file:///$OMQ_DIR/user/wsdl/enterprise.wsdl"
    username:
        type: string
        value: username@example.com
    password:
        type: string
        value: my_password
    token:
        type: string
        value: 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
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() for more information on the above options

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 to 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 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 are at least two consecutive ping errors 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, if the consecutive error limit is reached).

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).