Calling external HTTP(s) rest api's
In InterFormNG2 it is possible to call (most) external HTTP REST APIs / Webservices and form submits using workflow components.
The calls are based on RFC2616 Hypertext Transfer Protocol HTTP/1.1 https://www.ietf.org/rfc/rfc2616.txt
The external HTTP calls can be used to interact with third party software which supports REST API calls, including an almost unlimited number of Open REST APIs or automatization of form submits to a website.
Basic knowledge on how the HTTP protocol works is recommended.
HTTP methods supported
HTTP Post based methods
A HTTP post is a call where the parameters are encoded as part of the payload. It exists in the following variants: HTTP Patch, HTTP Put, HTTP Post
HTTP Get based methods
A HTTP get is a call where the parameters are a part of the URL.
Workflow components
The possible HTTP calls has four different workflow components, each for slightly different uses.
Common for all components
All components can convert a returned JSON document to XML for futher processing in InterFormNG2. The returned documents are added as the payload in the workflow and the following workflow variable is set: interformng.httpReturnCode=### where ### is the HTTP return code (200=OK, 403=Access denied etc)
Components
The HTTP Get requests calls an external REST API with parameters as part of the URL.
This is similair to the HTTP Get Request, except that the parameters are encoded as the HTTP payload.
This request sends the current workflow payload as the HTTP payload. This also means that no parameters can be added.
This request is mostly used for uploading a file to a web-service. This is a POST, but the content is encoded as a multipart body.
This request also has filepart description with the two fields:
File Part Name: This is the file part parameter name
File Part Filename: This is the filename of the file part
Example using post
We can login to InterFormNG2 using the HTTP Post Request.
Add the HTTP Post Request Component:
Set the following parameters:
URL: http://127.0.0.1:8086/oauth/token
Output type: XML
Convert JSON to XML: Checked
HTTP Method: Post
Header name: authorization
Header value: concat('basic',' ',ng:base64('interform:Io14oarPPnv3Bso10bagGA9Ovns2lvxt'))
(Header value must be an xpath expression)
Parameter names and values:
username=default/home
password=password
grant_type=password
(These are the default login/password, make sure to use the current ones)
When running this request, the following should be returned:
<?xml version="1.0" encoding="UTF-8"?>
<xml>
<access_token>eyJhbGciO......</access_token>
<token_type>bearer</token_type>
<refresh_token>eyJhbGciOiJI.....</refresh_token>
<expires_in>3600</expires_in>
<scope>read write</scope>
<pwChangeRequired>false</pwChangeRequired>
<tenantId>home</tenantId>
<jti>9959364f-e103-488e-9c23-aae4a3fd5c5d</jti>
</xml>
Workflow payload as request parameter
When calling a REST API, you may need to pass the workflow payload as a request parameter. Since the workflow payload can be any type of data, the workflow normally treats the payload as a binary object.
In reality the payload can be a text format, such as XML or JSON. When sending such a text-based payload to a REST API, you need to convert the payload from binary to text string. This can be done with the XPath function ng:payloadToString(encoding). The encoding parameter must be the character set encoding of the text payload (typically ‘utf-8’). The output from this function, is the payload as a string. It can be used in the HTTP REST workflow components, as shown in the screenshot.
It is also possible to use the contents of a workflow variable as parameter for a REST API. In some cases, the variable may also contain a binary representation of text data, for instance when the value is set with the component “From file to workflow variable” or one of the similar components. In this case, the function ng:varToString(variableName, encoding) can be used to convert the contents of the variable to a string, as shown in the screenshot.
Note that these functions cannot convert text payloads that are encoded with an initial BOM character (character sets UTF-8 BOM and UTF-16 BOM). The regular UTF-8/16 without BOM should be used instead.
