Extensions

Enterprises often have on-prem applications and databases that are deployed behind a corporate firewall.

Workato’s on-prem extensions allows you to connect to legacy applications using Java. Extensions are registered as Servlets in the Workato on-prem agent, and expose as REST endpoints which can be used from within a recipe.

When to use this:

• Application does not have REST / SOAP APIs.
• Application has a supported Java library.

When not to use this:

• Application has REST / SOAP APIs. Use the HTTP Connector or build a custom connection with the Connector SDK.
• You want to execute simple command-line scripts. Use Command-line scripts instead.

Prerequisites

OPA versions lower than 23.0 require you to install the Java 17 SDK (opens new window) manually. Refer to the On-prem agent version notes for more information.

Example

To explain Extensions, we'll walkthrough how to create a simple extension that performs a SHA-256 message digest. This extension takes the request body and returns a SHA-256 encrypted version of it. We will then enable it as a REST endpoint so that you can use this extension in a recipe.

Build Extension

Download the repository (opens new window) for this extension. This is a Gradle project which will serve as a base template that you can leverage on to write your own extensions.

The source file for the on-prem extension is located in src/main/java/com/mycompany/onprem/SecurityExtension.java

Run ./gradlew jar on the root folder to bootstrap Gradle and build the project. You will find the output in build/libs/opa-extensions-0.2.jar

Install Extension

To install the OPA extension, create a new directory called ext under the Workato agent directory and place opa-extensions-0.2.jar in the ext folder.

Update conf/config.yml with the classpath and newly added extension. This tells the on-prem agent where to find the jar files:

server:
  classpath: C:\\Program Files\\Workato Agent\\ext
extensions:
  security:
    controllerClass: com.mycompany.onprem.SecurityExtension
    secret: HA63A3043AMMMM

Note that the classpath value above should be set to the appropriate location, which may differ in your environment.

If you have multiple extensions, place all jar files in the ext folder and add a new entry under extensions:

server:
  classpath: C:\\Program Files\\Workato Agent\\ext
extensions:
  security:
    controllerClass: com.mycompany.onprem.SecurityExtension
    secret: HA63A3043AMMMM
  otherextension:
    controllerClass: com.mycompany.onprem.OtherExtension

The server parameter configuration property is as follows:

Property name	Description
classpath	Specifies the location of user-defined class

The extensions parameter configuration properties are as follows:

Property name	Description
security	This is the extension profile name that will be used in the SDK. Use a unique name for each extension.
controllerClass	A required field to inform the OPA which Java class to map the extension to.
secret	Optional environment property that is used in the Java class. Multiple properties can be added.

TROUBLESHOOT 520 CONNECTION FAILED ERRORS

The agent logs a 520 Connection Failed error when it can't start the extension. Refer to the 520 Connection Failed error during Java extension startup guide to learn how to resolve it.

Build SDK

In order to use the extension in a recipe, we need a custom connector (SDK) in Workato. Create an custom connector in the Connectors page (opens new window) with the following code:

{
  title: 'On-prem security',
  secure_tunnel: true,

  connection: {
    fields: [{ name: 'profile', hint: 'On-prem security connection profile' }],
    authorization: { type: 'none'},
    apply: ->() {
      headers('X-Workato-Connector': 'enforce')
    }
  },

  test: ->(connection) {
    post("http://localhost/ext/#{connection['profile']}/computeDigest", { payload: 'test' })
  },

  actions: {
    sha256_digest: {
      title: 'Create SHA-256 digest',
      description: 'Create <span class="provider">SHA-256</span> digest',

      input_fields: -> { [{ name: 'payload' }] },
      output_fields: -> { [{name: 'signature' }] },

      execute: ->(connection, input) {
        post("http://localhost/ext/#{connection['profile']}/computeDigest", input)
      }
    }
  }
}

Take note of the following in the SDK code:

• secure_tunnel is set to true which allows you to select an OPA when creating a connection. Make sure to select the OPA that has the extension.

• Header X-Workato-Connector: enforce is used to inform the OPA that this is a request to communicate with the OPA extension

• The path http://localhost/ext/#{connection['profile']}/computeDigest is defined in the Java class

@RequestMapping(path = "/computeDigest", method = RequestMethod.POST)