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
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 |
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 |
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
-
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
-
SAP S/4Hana REST API User Connections
- Description
- get_user_connection() returns a Sap4HanaRestClient object; socket performance is monitored.
- Example
my-sap = (
desc = My SAP S/4Hana REST HTTPS connection,
url = sap4hanarests://https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap,
apikey = V3EC5RWfWTTn9Gl5xWTVwevWHCT1vusdG,
timeout = 60000,
connect_timeout = 30000,
)
- 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 |
"timeout" | transfer timeout to use in milliseconds |
- See also
-
- Since
- Qorus 4.0.3.p2
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:
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:
%new-style
%requires tibae
const Subject = "QORE.Test.QORETest";
const MsgOut = (
"STRING" : "hello there",
);
const test_class = "/tibco/public/class/ae/Test";
sub init() {
}
%new-style
*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);
}
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
- 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:
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).