KB389906957: WebCenter - How to use External API Connections from Dashboards or Workflow node

WebCenter provides central and secure management of External API Connections. These API connections can easily be used from the Dashboard/Forms scripting API and Workflow. This document provides some pointers on how to work with these External API Connections.

An External API connection defines the information needed to connect to an external system: 

• the URL of the system
• Authentication method and credentials

When using the External API Connection you only need to provide the name of the connection. This allows changing the URL and credentials from such a connection without the need to adapt your scripts and workflows.

Procedure

In dashboards you can use External API Calls in Before Validation, On Change and Validation scripts. In workflows you can do External API calls from the Execute JavaScript node. Both scripting languages have similar API methods: API.doExternalAPICall(...) and API.doExternalApiCallWithBody(...)

For all following examples on the page we configured a External API Connection with the name "service" and base URL https://api.service.com/api/v2.

Path

The External API connection defines the base URL of the API end point. When using the connection it is only possible to call the base URL or a sub path of it is possible.

Whenever you are using the API connection, you specify the name of the connection and the path to be called.

Some examples:

Method

Whenever you make a HTTP request you need to chose which HTTP method you want to use. Supported HTTP Methods are GET, POST, PUT, PATCH and DELETE.

Query Parameters

If you need to provide query parameters, you define the Query Parameters as a map of key-value pairs.

API.doExternalApiCall(
    "service", 
    "GET", 
    "projects", 
    {
        "filter": "active projects", 
		"company": "Esko"
    }
);

Will result in following HTTP Call:

GET https://api.service.com/api/v2/projects?filter=active+projects&company=Esko

Headers 

Some API services need extra request headers to be sent. If these are needed for authentication, they should be configured in the External API Connection settings. However it is possible  to add headers to a specific request:

API.doExternalApiCall(
    "service", 
    "GET", 
    "projects", 
    {
        "filter": "active projects", 
		"company": "Esko"
    }, 
    {
        "Accept": "application/json"
    }
);

Will result in following HTTP Call:

GET https://api.service.com/api/v2/projects?filter=active+projects&company=Esko

with a header "Accept: application/json"

Request Body

For POST, PUT, PATCH and DELETE it is possible to provide a request body. This data is sent to the server so it can be processed.

WebCenter currently supports sending FORM, JSON or XML data.

Form

When you choose form data, the data is sent as application/x-www-form-urlencoded. Provide a set of key-value pairs that are transformed into formdata

API.doExternalApiCallWithBody(
  "service",
  "POST",
  "submitform",
  "FORM",
  {name: "Test 1234", description: "Submitting form data", value: 4000},
);

This will POST a form with values for name, descrpition and value to http://api.service.com/api/v2/submitform

JSON

Send JSON data to a POST http end point, with query parameter id

API.doExternalApiCallWithBody(
  "httpbin",
  "POST",
  "storeobject",
  "JSON",
  {
    description: "Example",
    items: [
        "JSON body", 
        "XML body", 
        "FORM body"
    ]
  },
  {id : "1234"}
);

This will send a POST request to http://api.service.com/api/v2/storeobject?id=1234 with a JSON body 

{
    description: "Example",
    items: [
        "JSON body", 
        "XML body", 
        "FORM body"
    ]
}

XML

Data of the request can also be send as an XML string.

API.doExternalApiCallWithBody(
  "service",
  "POST",
  "storedata",
  "XML",
  "<datablob><items><item>First item</item><item>Second Item</item></items></datablob>",
);

This will send a POST request to http://api.service.com/api/v2/storydata with <datablob><items><item>First item</item><item>Second Item</item></items></datablob> as body.

Response of External API Request

The script will wait until the service responds. It is possible to inspect the response of the server, a result object is returned on which you can retrieve the status code, headers and body as JavaScript object getBodyAsJSON() or a plain string getBodyAsText().

Example "Execute JavaScript" node that stores the result of the call in a task specifications STATUS_CODE and TEXT_ATTRIBUTE

var result = API.doExternalApiCall(
  "service",
  "GET",
  "projects",
  {
    filter: "active projects",
  },
  {
    Accept: "application/json",
  }
);

API.getTask()
    .getSpecification("STATUS_CODE")
    .setValue(result.getStatusCode());


API.getTask()
  .getSpecification("TEXT_ATTRIBUTE")