Connection Profiles ​

A single Workato on-prem agent (OPA) can connect to multiple on-prem applications. A connection profile uniquely identifies each application and contains configuration information required to connect.

Basics ​

• What's a connection profile?
• What types of systems can I connect to?
• How do I apply a new configuration?

What's a connection profile? ​

A connection profile is a file that uniquely identifies and contains information for an on-prem application. Profiles are stored in a configuration file located at <INSTALL_HOME>/conf/config.yml.

A typical config file looks something like this:

database:
  profile1:   # Connection names can't contain
    ...       # spaces or special characters
  profile2:   # But may contain underscores (_) and hyphens (-)
    ...

files:
  profile3:
    ...
  profile4:
    ...

jms:
  profile5:
    ...

ldap:
  profile6:
    ...

server:
  classpath:
    ...
  staging:
    ...

What types of systems can I connect to? ​

A config.yml file can contain profiles for the following system types:

• Databases
• On-prem file systems
• SAP
• Java messaging service
• Apache Kafka
• Active Directory
• HTTP profile
• NTLM
• Command-line scripts
• Extensions
• Server

You can also configure proxy servers for OPAs installed on a server with limited internet connectivity.

How do I apply a new configuration? ​

By default, your OPA must be restarted whenever a change is made to config.yml. Refer to the Running your on-prem agent guide for more info.

To allow the on-prem agent apply the changes automatically, add the following to the top of your config.yml file to use the autoReload option

config:
  autoReload: true

When enabled, changes made to config.yml will be picked up by autoReload. You won't need to manually restart the OPA.

Database profiles ​

Database connection profiles provide the information your on-prem agent (OPA) uses to connect to a database. Connection profiles are located in the database section of the config.yml file.

OPA supports connections to multiple databases. Add a section under the database key for each database you plan to connect to. For example:

database:
  your-connection-name:         # Specify the connection name, ex: sales-database
    adapter: sqlserver
    host: localhost
    port: 1433
    database: sales
    username: sales_analyst
    password: secretPassword456

In this section, we'll cover:

• Profile properties
• Supported database types
• Example profile configurations

Profile Properties ​

Database connection profiles can contain the following properties:

Supported Databases ​

The following table contains information about the databases OPA currently supports, including:

• Database name: The name of the database
• Adapter: The adapter value for the database. This value is used to specify the type of database OPA is connecting to.
• Default port: The default port for the database.
• Notes: Notes about configuring the database.

Example Configurations ​

Click the blocks to display the example.

database:
  sales:
    adapter: sqlserver
    host: localhost
    port: 1433
    database: sales
    username: sales_analyst
    password: secretPassword123
  operations:
    adapter: redshift
    host: localhost
    port: 5439
    database: customers
    username: cs_analyst
    password: secretPassword789

database:
  sales:
    url: jdbc:postgresql://sales.database:5432/sales
    username: sales_analyst
    password: secretPassword123
    ApplicationName: workato

database:
  sales_database:
    adapter: sqlserver
    host: localhost
    port: 1433
    database: test
    username: sales_user
    password: { secret: 'sales-db-password-password' }

database:
  erp:
    url: jdbc:oracle:thin:@localhost:1521/PROD
    username: admin
    password: SecretPassword456

database:
  tpc:
    url: jdbc:presto://warehouse.intra:8889/tpch
    driverClass: com.facebook.presto.jdbc.PrestoDriver
    adapter: jdbc
    username: my_user

server:
  classpath: jdbc

database:
  sales:
    adapter: sqlserver
    url: jdbc:sqlserver://[Server/Host]\[Instance]
    username: user
    password: Secret123

database:
  sales:
    adapter: postgresql
    host: localhost
    port: 5432
    database: sales
    username: sales_analyst
    password: secretPassword123
    ssl:
      cert: /path/client_ca.crt
      trustAll: false
      verifyHost: true

On-prem files Profile ​

Working with on-prem files requires you to define a file system profile in the files section. You need to specify the base folder for file access as it will be used for resolving relative paths. A folder named HR in the C:\Documents\ directory will be configured like this:

files:
  hrfiles:
    base: "C:\\Documents\\HR"

In another example, if you wish to provide access to the employees folder in the Desktop directory, the configuration will have a file path that looks something like this:

files:
  hrfiles:
    base: "/Users/me/Desktop/employees"

FTP(S) Profile ​

To set up the FTP(S) connection you have to define a profile in the ftp section. You need to specify the host and the port of the FTP server along with the credentials. A simple connection to the FTP server will be configured like this:

ftp:
  ftp_profile_1:
    hostname: myftpserver.com
    port: 21
    user: username
    password: secretpassword

The following properties are supported:

Below is an example for public/private key pair and password authentication type:

ftp:
  ftp_profile_key_protected:
    hostname: myftpserver.com
    port: 21
    user: username
    password: secretpassword
    ssl:
      implicit: false
      cert: /path/to/PEM-encoded-certificate-or-trusted-CA
      trustAll: true

Refer to the FTP connector documentation for more information.

SFTP Profile ​

To set up the SFTP connection you have to define a profile in the sftp section. You need to specify the host and the port of the SFTP server along with the credentials. A simple connection to the SFTP server will be configured like this:

sftp:
  sftp_profile_1:
    host: mysftpserver.com
    port: 22
    user: username
    password: secretpassword

The following properties are supported:

Below is an example for public/private key pair and password authentication type:

sftp:
  sftp_profile_key_protected:
    host: mysftpserver.com
    port: 22
    user: username
    password: secretpassword
    host_key_fingerprint: AAAAC3NzaC1lZDI1NTE5AAAAIDnkCeZXGyvQmXJ7VfbTD65NG2u0wcMA1gC5Um3tJ/2P
    private_key: /path/to/id_rsa
    passphrase: password  #if private_key is password-protected

Refer to the SFTP connector documentation for more information.

SSH-RSA support ​

SSH-RSA relies on SHA-1, which no longer meets modern security standards. Workato doesn't support SSH-RSA authentication for cloud connections to SFTP. Use the Workato OPA to create an on-prem connection if you need to authenticate using SSH-RSA, or contact your server administrator to enable a stronger host key algorithm.

SMB Profile ​

To set up the SMB connection to your shared network location you must first define a profile in the smb section. You must specify the host, port, and share name of the SMB along with the credentials. The following example configures a simple connection to the SMB:

smb:
  smb_profile_1:
    host: some-host.amazonaws.com
    port: 445
    shareName: SampleSharedFolder
    username: username
    password: secretpassword
    domain: optionalDomainName

The following properties are supported:

Refer to the SMB connector documentation for more information.

SAP Profile ​

For a SAP connection profile, you must define the server and sap section together.

There are two connection types that the SAP connector supports - Direct connections or Message Server connections.

If these ports differ from our defaults, please contact Workato support.

jco_overrides:
  opt.idoc_reception_strategy: 'LEGACY'   # Value is case-insensitive

SAP - Direct Connection ​

The following is an example of a Direct connection type. Use this connection type if the SAP system is directly exposed as an application server.

server:
  classpath:
    - lib_ext

sap:
  sap_profile_1: # The on-prem agent connection profile name.
    network_connection:
      gateway_host: "xx.xx.xx.xx"
      system_number: "XX"
      program_id: "WORKATO"
      metadata_refresh_interval: "10"
      quality_of_protection: 3
      partner_name: "p:CN=EH8, OU=I0021153688, OU=SAP Web AS, O=SAP Trust Community, C=DE"
    user_logon:
      client: "800"
      language: "EN"
      user: "USERN"
      password: "PASSW"
    jco_overrides:
      jco.client.snc_myname: "Canonical name of the client certificate"

Parameter (JCO Connection Property)	Description	Click to expand image
gateway_host (jco.client.ashost) required	The IP address or DNS name of the SAP application server you are directly connecting to. This can be seen on the SAP Logon Pad used to log in to your on-premise SAP application server. Accepts the following format: xx.xx.xx.xx.
system_number (jco.client.sysnr) optional	The SAP system number that identifies the logical port on which the application server listens for incoming requests. Commonly found from TCP port 33XX, where XX is the system number. Defaults to 00.
program_id (jco.server.progid) conditional	The program ID given to the RFC destination linked to Workato in the SM59 transaction. Required if you use IDocs. Not needed for connections that use only RFCs.
metadata_refresh_interval optional	The interval in minutes to refresh metadata from SAP (except JCo cache). Defaults to 1440 minutes (24 hours).
quality_of_protection (jco.client.snc_qop) optional	The quality of the protection level to apply. Enter one of the following numbers: 1: Authentication only 2: Integrity protection (authentication) 3: Privacy protection (integrity and authentication) 8: Default protection 9: Maximum protection
partner_name (jco.client.snc_partnername) conditional	The SNC partner found in the STRUST transaction under SNC SAPCryptolib. Must be prepended with p:. For example: p:CN=EH8, OU=I0021153688, OU=SAP Web AS, O=SAP Trust Community, C=DE. Required if you configure Secure Network Communication (SNC).
client (jco.client.client) required	The three-digit client number used to connect to Workato. Use the same client you log in to with your SAP Logon Pad.
language (jco.client.lang) optional	The SAP Logon language to use. Valid values include two-character ISO language codes or one-character SAP language codes. Defaults to the user or system's default language.
user (jco.client.user) required	The SAP user provisioned for Workato. We recommend you use a background user and disable dialog properties.
password (jco.client.passwd) required	The SAP user password.
jco.client.snc_myname conditional	The canonical name of the client certificate to use for the connection. Required if you configure SNC.

SAP - Message Server Connection ​

The following is an example of a Message Server connection type. Use this connection type when the SAP system is behind a message server gateway.

server:
  classpath:
    - lib_ext

sap:
  sap_profile_2: # The on-prem agent connection profile name.
    network_connection:
      message_server_host: "xx.xx.xx.xx"
      logon_group: "XXXXX"
      system_id: "XXX"
      program_id: "WORKATO"
      metadata_refresh_interval: "10"
      quality_of_protection: 3
      partner_name: "p:CN=EH8, OU=I0021153688, OU=SAP Web AS, O=SAP Trust Community, C=DE"
    user_logon:
      client: "800"
      language: "EN"
      user: "USERN"
      password: "PASSW"
    jco_overrides:
      jco.client.snc_myname: "Canonical name of the client certificate"
      jco.client.msserv: "36<XX>"
      jco.server.msserv: "36<XX>"

Parameter (JCO Connection Property)	Description	Click to expand image
message_server_host (jco.client.mshost) required	The IP address or DNS name of the Message Server you are connecting to. Accepts the following format: xx.xx.xx.xx.
logon_group (jco.client.group) optional	The logical group name of the application servers. Can be found in the SMLG transaction. Common default group names include PUBLIC or SPACE.
system_id required	The system ID of the system the message server belongs to. Refer to SAP Note 52959 if you encounter a connection error.
program_id (jco.server.progid) conditional	The program ID given to the RFC destination linked to Workato in the SM59 transaction. Required if you use IDocs. Not needed for connections that use only RFCs.
metadata_refresh_interval optional	The interval in minutes to refresh metadata from SAP (except JCo cache). Defaults to 1440 minutes (24 hours).
quality_of_protection (jco.client.snc_qop) optional	The quality of the protection level to apply. Enter one of the following numbers: 1: Authentication only 2: Integrity protection (authentication) 3: Privacy protection (integrity and authentication) 8: Default protection 9: Maximum protection
partner_name (jco.client.snc_partnername) conditional	The SNC partner found in the STRUST transaction under SNC SAPCryptolib. Must be prepended with p:. For example: p:CN=EH8, OU=I0021153688, OU=SAP Web AS, O=SAP Trust Community, C=DE. Required if you configure Secure Network Communication (SNC).
client (jco.client.client) required	The three-digit client number used to connect to Workato. Use the same client you log in to with your SAP Logon Pad.
language (jco.client.lang) optional	The SAP Logon language to use. Valid values include two-character ISO language codes or one-character SAP language codes. Defaults to the user or system's default language.
user (jco.client.user) required	The SAP user provisioned for Workato. We recommend you use a background user and disable dialog properties.
password (jco.client.passwd) required	The SAP user password.
jco.client.snc_myname conditional	The canonical name of the client certificate to use for the connection. Required if you configure SNC.
jco.client.msserv optional	The client port number. Can be found in the SMMS transaction. Overrides the default 3600 port number.
jco.server.msserv optional	The message server port number. Can be found in the SMMS transaction. Overrides the default 3600 port number.

JMS Profile ​

JMS connection profiles must be defined in the jms section. A JMS provider is specified by provider property of a connection profile. The following JMS providers are supported by the on-prem agent:

Amazon SQS ​

You need the following configuration properties when connecting to Amazon SQS:

jms:
  MyAmazonProfile:
    provider: amazon-sqs
    region: <Your Amazon API region, eg 'us-east-2'>
    accessKey: <Your Amazon API access key>
    secretKey: <Your Amazon API secret>

Ensure your SQS queue exists before sending messages.

Apache ActiveMQ ​

For connecting to a running ActiveMQ broker you only need to specify the broker URL:

jms:
  MyActiveMQProfile:
    provider: activemq
    url: tcp://localhost:61616

The ActiveMQ broker can't be embedded in the agent. OPA doesn't support vm:// broker connections.

Azure Service Bus ​

Azure Service Bus uses a custom JMS provider. Use the following configuration properties to connect, replacing <HOST_NAME>, <POLICY_NAME>, and <PRIMARY_KEY> with values from Azure Service Bus:

jms:
  azureServiceBus:
    provider: custom
    class: org.apache.qpid.jms.JmsConnectionFactory
    remoteURI: amqps://<HOST_NAME>.servicebus.windows.net
    username: <POLICY_NAME>
    password: "<PRIMARY_KEY>"

Download the required JAR files and dependencies and place them in your lib_ext folder.

Add the classpath inside the config.yml file.

server:
  classpath: lib_ext

Apache Kafka Profile ​

Kafka connection profiles must be defined in the kafka section. You need the following configuration properties when connecting to Kafka:

kafka:
  MyKafkaProfile:
    ... connection properties ...

You can provide any Kafka producer or consumer configuration properties, for example, bootstrap.servers or batch_size.

However, some properties are overridden by the on-prem agent and cannot be configured. You will get a warning when trying to redefine a protected property. Some examples of these protected properties:

Workato Agent also supports the following (non-Kafka) configuration properties:

ssl.* options above can be used when connecting to Kafka using SSL/TLS and allows you to keep PEM-encoded certificates and private keys inside the config.yml file. Any YAML-compatible multiline syntax could be used, for instance:

kafka:
  MyKafkaProfile:
    ssl.truststore:
    |
      -----BEGIN CERTIFICATE-----
      502mPNNAYkY4a7Zu84DLCXLFurEa4BhLBqLkzC6WdTrBN9z6Rp/svTIl6VgjSTP6
      .....
      -----END CERTIFICATE-----

Note that password-protected private keys cannot be inlined.

You must configure Workato's on-prem agent as a Kafka client to connect Apache Kafka to Workato.

security.protocol: SASL_SSL
sasl.mechanism: AWS_MSK_IAM
sasl.jaas.config: software.amazon.msk.auth.iam.IAMLoginModule required;
sasl.client.callback.handler.class: software.amazon.msk.auth.iam.IAMClientCallbackHandler

security.protocol: SASL_SSL
sasl.mechanism: SCRAM-SHA-256
sasl.jaas.config: org.apache.kafka.common.security.scram.ScramLoginModule required username=YOUR_USERNAME password=YOUR_PASSWORD;

security.protocol: SSL
ssl.keystore.location: /PATH/TO/KEYSTORE.jks
ssl.keystore.password: YOUR_KEYSTORE_PASSWORD
ssl.truststore.location: /PATH/TO/TRUSTSTORE.jks
ssl.truststore.password: YOUR_TRUSTSTORE_PASSWORD

Active Directory Profile ​

Active Directory connection profiles must be defined in the ldap section. Example profile:

ldap:
  active_directory_main:
    url:
      - ldap://acme1.ldap.com:389
      - ldaps://acme2.ldap.com:636
    username: Administrator
    password: foobar
    base: dc=acme,dc=com
    ssl:
      cert: /path/to/PEM-encoded-certificate-or-trusted-CA
      trustAll: true

HTTP Profile ​

The http configuration section enables you to configure agent access to internal HTTPS resources. Refer to the following yaml file as an example of an http config.yml:

http:
  connectTimeout: 5000
  keepAlive: true
  ssl:
    trustAll: false
    verifyHost: true
    cert:
    |
      -----BEGIN CERTIFICATE-----
      MIIF3TCCBMWgAwIBAgIQBlp2+roj8DZRf7VwurC8BjANBgkqhkiG9w0BAQsFADBG
      .....
      -----END CERTIFICATE-----
    key: /path/PEM-encoded-private-key
    pem: /path/PEM-encoded-certificate-or-trusted-CA

OPA uses a set of root Certification Authority (CA) certificates from the built-in JRE to validate HTTPS connections by default. For internal HTTPS resources that use self-signed certificates, you can configure the agent to allow access by setting the ssl.cert property to the server certificate file path or its PEM-encoded value to enable self-signed certificates. Alternatively, you can set the ssl.trustAll property to true to trust all server certificates.

The agent also supports mutual TLS (mTLS) for enhanced security. You must specify the client’s private key with the ssl.key property and provide the client certificate with the ssl.pem property if you plan to use mTLS.

Server certificates typically require the Common Name or Subject Alternate Name to match the target hostname. If a mismatch occurs, disable hostname verification by setting the ssl.verifyHost property to false. Hostname verification is enabled with this property set to true by default.

NTLM Profile ​

Certain HTTP resources require NTLM authentication. This can be done using a NTLM connection profile. Here are some example NTLM profiles:

ntlm:
  MyNtlmProfile:
    auth: "username:password@domain/workstation"
    base_url: "http://myntlmhost.com"
    cm_default_max_per_route: 15
    cm_max_total: 100
    verifyHost: true
    trustAll: false

  AnotherNtlmProfile:
    auth: "domain/workstation"
    username: "username"
    password: "password"
    base_url: "http://myntlmhost.com"
    cm_default_max_per_route: 15
    cm_max_total: 100
    verifyHost: true
    trustAll: false

The following profile properties are supported:

HTTP methods supported for NTLM connections are GET, POST, PUT, PATCH, DELETE and HEAD.

Command-line Scripts Profile ​

This profile allows users to run arbitrary scripts or commands on OPA. The script definition in the config file can have parameters.

When you declare an action, you need to specify the values of the parameters.

An example profile on Unix can look like this:

command_line_scripts:
  workday_reports:
    concurrency_limit: 3
    timeout: 30
    scripts:
     copy_file:
       name: Copy file
       command:
         - /bin/cp
         - '{{source_file}}'
         - '{{target_directory}}'
       parameters:
         - { name: source_file }
         - { name: target_directory }

     append_file_to_another:
       name: Append file to another
       command:
         - bash
         - -c
         - cat {{source_file}} >> {{target_file}}
       parameters:
         # Parameter quoting
         - { name: source_file, quote: '"' }
         # Advanced parameter quoting
         - { name: target_file, quote: { start: '"', end: '"', quote: '"', escape_char: \ } }

     generate_report:
       name: Generate report
       command:
         - python
         - /home/user/script.py
         - --from
         - '{{from_date}}'
         # Conditional fragment
         - { value: --to, if: to_date }
         # Conditional fragment
         - { value: '{{to_date}}', if: to_date }
       parameters:
         - { name: from_date }
         - { name: to_date, schema: { optional: true, control_type: select, pick_list: [01/01/2018, 02/02/2018] } }

The command-line script profiles are placed in the command_line_scripts section in config.yml. Each profile can contain multiple scripts. The profile configuration properties are as follows:

If the quote configuration is a string, its value is considered as the value of the start, end and quote properties, and the escape_char property value is set to '\' on Unix and '""' on Windows.

Extensions Profile ​

Working with Java extensions requires you to define an extensions profile. You need a server section to define where the jar files are located, and an extensions section to create individual profiles for the Java classes. A Java extension will be configured like this.

server:
  classpath: ext

extensions:
  security:
    controllerClass: com.mycompany.onprem.SecurityExtension
    secret: HA63A3043AMMMM

The server parameter configuration property is as follows:

Each extensions profile configuration properties are as follows:

Find out how to create a Java extension.

Server Profile ​

Server profiles define where OPA assets are located on the on-prem server. Server profiles are located in the server section of config.yml.

server:
  classpath: lib_ext
  staging: staging

In this section, we'll cover:

• Profile properties
• Example profile configurations

Profile Properties ​

Server profiles can contain the following properties:

Example Configurations ​

Let's look at some example profile configurations using the following directory structure. In this example, the on-prem agent is installed in /opt/workato-agent:

/opt
├── /workato_agent
    ├── /conf
    ├── /bin
    ├── /lib_ext
    ├── /staging

The following example defines a jdbc directory that contains Java driver classes or user-defined classes:

server:
  classpath: lib_ext

Next, we'll demonstrate setting the staging property. This property defines where the OPA temporarily stores files during loading to the target system.

For example, when executing the SQL Server Export query result action, CSV output will be temporary stored in the /staging directory and deleted after the file is loaded:

server:
  classpath: lib_ext
  staging: staging