Connected Services

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

In order to accomplish this, an Owner user has to set up the Operations they want to interact with, and the Authorization required (if needed) to access them.
In other words, similar to its software counterpart, a connected service is the abstraction of a set of operations that belong under the same logical group and share the same access (owners) and authorization policies.

Once 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: service('ThisIsAService', 'OperationA', <payload_data>)
will call OperationA defined in ThisIsAService and send the payload_data.

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. For GET requests the payload_data is appended as query parameters to the URL. For POST requests the payload_data is 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, 3 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
  Requires Consumer Key (Client ID), Consumer Secret (Client Secret), Token API URL, Username and Password.

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 Auth will be then used with all the Operations in the Service.

As Authorization handles sensible 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 an User is not included as an Owner on a specific Service, they can still interact with it, but not make changes. This means:

a. They are allowed to call the Service and any of its Operations using JMES’s service function.
b. They get a very 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 recieved, it is shown as a standard JMES error toast.

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

Basic example

Comparison with Postman

Postman served as the base structure for Connected Services, as can be seen in this simple case based on the previous example: