The concept of a Connected service is simple: an external service which we can fetch data from.

In order to accomplish this, an Owner has to set up the Operations they want to interact with, and the authorization required to access them. A connected service is the abstraction of a set of operations that belong under the same logical group and share the same access and authorization policies.

After it's set up, a service can be requested from JMES transformations (e.g. Templates, Custom Functions) using the service function, with the service name, operation name and payload as parameters. For example, a call like this:

service('ThisIsAService', 'OperationA', <payload_data>)

will call OperationA defined in ThisIsAService and send the payload_data.

How to create a Connected service

1. Navigate to Connected Services in the Navigation Pane.
2. Select New Connected Service.
3. Enter the name for your new service.
4. Select Create.

Open the new Connected Service to set it up.

Operations

Essentially an endpoint, Operations are the core element behind Connected services.
Each of them consist of 4 elements:

• Name
  • Easily identifiable name for the operation.
• HTTP Method
  • Currently, only GET and POST are available. The payload_data can be appended as query parameters to the URL for both GET and POST requests. For POST requests the payload_data can also inserted into the body of the request.
• URL
  • Endpoint URI to be consumed.
• Response Type
  • “Suggested” way for the response data to be interpreted as when there’s no content type specified.

Authorization

In many cases, some sort of authorization is required to interact with the operations.
Currently, these types are supported:

• None
• Static Header
  • Key-value combination sent as a Header.
  • Can be used for other types, such as API key, Bearer token, Basic auth, etc.
• OAuth2 Client Credentials (WSO2)
  • Client credentials grant for WSO2 API manager.
  • Requires Consumer key (Client ID), Consumer secret (Client secret), Token API URL, and Token header prefix (default Basic).
• OAuth2 Password Credentials Grant
  • Requires Consumer key (Client ID), Consumer secret (Client secret), Token API URL, username and password.
• OAuth2 Client Credentials Grant
  • Requires Consumer key (Client ID), Consumer secret (Client secret), Token API URL.

As long as it is not saved, it is possible to change the type without affecting the service or currently running operations.
Once you do, this authorization will be then used with all the operations in the service.

As authorization handles sensitive data, it is NOT preserved during backup operations.

Owners

Owners are users granted permission to make changes to the service, identified by their registered email.
All owners share the same level of privileges, but the current user cannot remove themselves.

Non-owner Users

When a user is not an owner on a specific service, they can still interact with it, but not make changes. This means:

• They are allowed to call the service and any of its operations using the service function.
• They get a simplified read-only list of operations when accessing the service itself.

Result

Errors

Since a Connected service is called as a JMES function, when an error or invalid response is received, it is shown as a standard JMES error notification.

Success and Type Parsing

How the response is interpreted depends on both the response’s Content-Type and the user-supplied Response Type (see Operations): Priority goes to the Content-Type, and only when it is set as “any” MIME-type (/) or is not defined does the user’s take place.

Currently, response content is handled in 3 ways:

• Plain Text – Text (text/*), XML (application/xml)
• JSON – JSON (application/json)
• Base64 string – Images (image/*), OpenXML (application/vnd.openxmlformats.*), other binary data.

Examples

• Setting up a Connected service:

  

• Calling a Connected service:

  

• Result: