Connection Profiles

A single Workato on-premises agent can be used to connect with multiple on-premises applications. A connection profile uniquely identifies each one and contains configuration information required to connect to that application.

Profiles are configured in the <INSTALL_HOME>/conf/config.yml. A config file can contain profiles to a few types of systems:

• Databases
• On-premises file systems
• Java messaging service
• Apache Kafka
• Active directory
• HTTP resource
• NTLM

• Command-line scripts

  Additionally, you can configure proxy servers for on-premises agents installed in a server with limited internet connectivity.

  A typical config file will look something like this:

database:
  profile1:
    ...
  profile2:
    ...

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

jms:
  profile5:
    ...

ldap:
  profile6:
    ...

Do not use spaces or special characters in connection profile names.

Applying a new configuration

A running on-premises agent automatically applies any changes made to the configuration file. Changes to proxy server settings require you to restart the agent.

Database connection profile

Database connection profiles are located in the database section of <INSTALL_HOME>/conf/config.yml.

A database type is specified either by using the adapter property or a complete JDBC URL provided in the url property. Using the following adapter values for the respective database you are connecting to. The following databases are supported by the on-premises agent - use them as adapter values for the respective databases you connect to.

port numbers can be omitted when matching defaults for a given database type.

Here's a sample SQL server configuration for connecting to a specific instance:

database:
  sales:
    adapter: sqlserver
    host: localhost
    port: 1433
    database: sales
    username: me
    password: foobar

Here's a sample PostgreSQL database using url property in the configuration:

database:
  sales:
    url: jdbc:postgresql://sales.database:5432/sales
    username: joe
    password: Secret123
    ApplicationName: workato

When working with Oracle database, you may be connecting to either an SID or Service. If you are using SID, you can use both ways to define the profile. First, the

Using adapter property:

database:
  erp:
    adapter: oracle
    host: localhost
    port: 1521
    database: XE
    username: admin
    password: xxx

Using url property:

database:
  erp:
    url: jdbc:oracle:thin:@localhost:1521:XE
    username: admin
    password: xxx

When connecting to an Oracle Service, use the url property:

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

JDBC connection profile

When creating connection profile to other JDBC-compatible databases, the configuration is special. These profiles require url and driverClass properties, where url is a valid JDBC URL and driverClass provides fully-qualified name of JDBC driver class for the given database. The driver class must be available on the agent's classpath; note that your agent's classpath can be extended in the server section of the configuration file:

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

server:
  classpath: /opt/workato-agent/jdbc

On-premises files connection profile

Working with on-premises 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 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"

JMS connection 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-premises 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>

Note that you need to make sure your SQS queue is created 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

ActiveMQ broker cannot be embedded into the agent. Using any vm:// broker connections is not supported.

Apache Kafka connection 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 consumer or producer configuration properties, e.g. bootstrap.servers or batch_size.

However, some properties are overridden by the on-premises 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.

Active Directory connection profile

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

ldap:
  active_directory_main:
    url: ldaps://acme.ldap.com:636
    username: cn=Administrator
    password: foobar
    base: dc=acme,dc=com

where profile configuration properties are:

HTTP resources

The http configuration section allows configuring agent access to internal HTTPS resources:

http:
  trustAll: true
  verifyHost: true

The agent may be configured to allow accessing internal HTTPS resources which use self-signed certificates. To enable self-signed certificates set trustAll property to true.

Normally a server certificate's Common Name (or Subject Alternate Name) field should match the target hostname. If you want the agent to accept server certificates with non-matching hostname, disable hostname verification by setting verifyHost property to false (defaults to true).

NTLM connection profile

Certain HTTP resources require NTLM authentication. This can be done using a NTLM connection profile. An example profile should look like this:

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

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:

The hash key is used as an unique identifier for a script profile. The script configuration properties are as follows:

The command invocation element configuration can be just a string, but also can contain these properties:

The parameter configuration properties are as follows:

The quote configuration can just be a string or have properties. The 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.

The parameter schema configuration can have properties as follows: