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:

UserApi::getRemoteRpcConnection(): returns a QorusSystemAPIHelper object for communicating with the remote Qorus instance's RPC API
UserApi::getRemoteRestConnection(): returns a QorusSystemRestHelper object for communicating with the remote Qorus instance's REST API

Note: Each of the APIs above includes a register_dependency argument that can be used to supress the creation of any dependency between the interface and the connection; see the API method documentation for more information.

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

Defining Connections

User Connections

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

UserApi::getUserConnection(): returns the connection object described by the user connection

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

AwsRestClient::AwsRestConnection
AwsRestClient::constructor() for more information on the above options

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

BillwerkRestClient::BillwerkRestConnection
BillwerkRestClient::constructor() for more information on the above options

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

CdsRestClient::CdsRestClient
CdsRestClient::constructor() for more information on the above options

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

ConnectionProvider::HttpConnection
HTTPClient::constructor(hash opts) for more information on the above options

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

JsonRpcConnection::JsonRpcConnection
JsonRpcClient::constructor() for more information on the above options

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

RestClient::RestConnection
RestClient::constructor() for more information on the above options

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

Sap4HanaRestClient::Sap4HanaRestClient
Sap4HanaRestClient::constructor() for more information on the above options

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

SewioRestClient::SewioRestConnection
SewioRestClient::constructor() for more information on the above options

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

SewioWebSocketClient::SewioWebSocketConnection
SewioWebSocketClient::constructor() for more information on the above options

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

SalesforceRestClient::SalesforceRestConnection
SalesforceRestClient::constructor() for more information on the above options

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

ServiceNowRestClient::ServiceNowRestClient
ServiceNowRestClient::constructor() for more information on the above options

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

SoapClient::SoapConnection
SoapClient::constructor(hash opts) for more information on the above options

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

WebSocketClient::WebSocketConnectionObject
WebSocketClient::constructor() for more information on the above options

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

XmlRpcConnection::XmlRpcConnection
XmlRpcClient::constructor() for more information on the above options

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

YamlRpcClient::YamlRpcConnection
YamlRpcClient::constructor() for more information on the above options

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

ZeyosRestClient::ZeyosRestConnection
ZeyosRestClient::constructor() for more information on the above options

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:

Python / Java / Qore: UserApi::getDatasourceDedicated() gets a dedicated Datasource object with a transient connection to the DB server (normally UserApi::getDatasourcePool() should be used instead)
Python / Java / Qore: UserApi::getDatasourcePool(): gets a DatasourcePool object for the given datasource; this is the recommended way to get a database connection

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%host:1521

Another example for a jdbc connection to an MS SQL Server database:

db://jdbc:user/pass@@{url=sqlserver://hostname;integratedSecurity=false;encrypt=false;classpath=$OMQ_DIR/user/jar/mssql-jdbc-12.2.0.jre11.jar}

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

Defining Connections

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.

Datasource "coord-mode"

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%host:1521{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
When coord-mode is enabled, Qorus will ensure that the maximum number of connection is respected for active SQL, but a larger number of connections may remain open but inactive, as inactive connections are cached in each process

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

Table of Contents

Introduction to Connections

Qorus to Qorus Connections

User Connections

AWS REST User Connections

billwerk.com REST API User Connections

Microsoft Dynamics 365 / Common Data Service REST User Connections

Filesystem/Directory User Connections

FTP User Connections

HTTP User Connections

JSON-RPC User Connections

POP3 User Connections

REST User Connections

SAP S/4Hana REST API User Connections

Sewio.net RTLS Studio REST API User Connections

Sewio WebSocket User Connections

Salesforce.com REST User Connections

SFTP Connections

SMTP Connections

ServiceNow REST User Connections

SOAP Connections

TELNET User Connections

WebSocket User Connections

XML-RPC User Connections

YAML-RPC User Connections

Zeyos.com REST API User Connections

SalesforceSoapConnection User Connection Module

Datasource Connections

Datasource Connection Pools and the qdsp Mode

Datasource "coord-mode"

Connection Monitoring

Monitoring Overview

Connection Dependencies