Call REST Service

Call Rest Service:
This workflow task enables Administrators to call an external web services from an automatic workflow task without coding.

General Settings
More information on general workflow task settings can be found here:
Workflow Tasks

Edit
Opens a dialog that lets you configure the REST call settings.

Icon	Description
	Add a new REST call.
	Edit a rest request.
	Delete a REST request.
	Move the REST request up in the list. By default, the calls are executed top to bottom.
	Move the REST request down in the list.

Name:
Add a name for the REST call.

Scripting ID
Add a scripting ID for the REST call.

Credential
Select a saved credential from the central credential store to authenticate against the provider of the endpoint the call is made to.
Credentials

Verb
Select the HTTP request method from the drop-down menu.

Drop-down menu options

Request	Function
GET	Retrieves data from a server at the specified resource.
POST	Sends data to the API server to create or update a resource.
PUT	Sends data to the API to update or create a resource. The difference is that PUT requests will always produce the same result.
DELETE	Deletes the resource at the specified resource.
PATCH	Similar to POST and PUT options, but only applies to partial modifications to the resource.

URL Field
The placeholder for the URL of the Web Service call.

Macros
Opens a dialog with all available macros.

Script
An initialization script can be created. This script will be executed before the execution of the field assignments. Variables and functions that will be available for the assignment scripts can also be defined here.

More information on scripting properties and functions can be found below.

Test
Runs a test API call that checks whether a communication can be made to the Web Service and if a response can be achieved. Opens a dialog to demonstrate the outcome of the test.

Parameters
List the parameters required to send and receive.

Add
Add a Parameter.

Remove
Remove a Parameter.

Header
List the Headers required to send or receive.

Document
If a document should be sent to a 3rd party service via the REST call, configure the content and sending method.

Body
List the JSON Values and Objects.

Insert
Select either a JSON Object or Value to be listed.

Remove
Remove a JSON Object/ Value.

Load JSON request
Upload a JSON file into the Body. The JSON can either be added from a file on your device or directly from your clipboard.

Response
Define the response that should be received from the 3rd party service.

Success codes
List the success codes that the API call should consider to be successful.

Script
A response script with instructions on how to process the REST response can be added here.

More information on scripting properties and functions can be found below.

Response Type
Select between 'Structured(JSON)' and 'Binary(document file)'. Selecting Binary will allow the resulting file to be added to the document used by the workflow. Users can select between appending the file to the document, or replacing existing attachments.

Load JSON response
Upload a JSON file into the Body. The JSON response can either be loaded from a file on your device or directly added from your clipboard.

Note:

REST calls were designed for making outgoing calls to third-party applications. Although it’s possible to use REST calls to call the Therefore API, to solve advanced requirements, the feature is limited especially when working with index data information.
In order for third-party applications to access Therefore™ while bypassing two-factor authentication, they will require a Service Account. Please see our reference below for more information:
Users and Groups

Scripting with REST calls

The following properties and JavaScript functions can be used in initialization and/or response scripts that are part of the Call REST Service or Referenced Web Service task. The format they are displayed in is:

CallREST.NextRequest

Additionally, helper functions that are not specific to Call REST scripts are also available. A list can be found on the following page:

Objects and Functions

Name	Location	Description	Usage Example
BodyJSONContent	Initialization script	This property can be used to define more complex JSON structures than the Body tab supports. If this property is set, it overrides the JSON in the body tab. If the ContentType property is set accordingly this property can be filled with non-JSON string content.	`RESTCall.BodyJsonContent = JSON.stringify(inv)` Please see below for a sample script.
ContentType	Initialization script	By default, the content type of a REST call is application/json. Using this property it is possible to set a different content type. This is useful if a third-party service only accepts a content type that is not application/json. A list of content types can be found at the following external link: https://www.iana.org/assignments/media-types/media-types.xhtml?utm	`RESTCall.ContentType = "application/x-www-form-urlencoded"`
GetResponseHeader	Response script	This JavaScript function gets the header field value for a given header field name. The header field name can be specified by setting the parameter as shown in the example on the right.	`RESTCall.GetResponseHeader("header field name")`
LoadRowsNow	Response script	This property can only be used for Referenced Web Service configurations, not for Call REST Service workflow tasks. This property is a boolean flag that can be set to true or false. The default is false. If set to true, this property triggers the immediate filling of the local referenced database table from the request response. If set to false, the local database table is only filled when all REST requests have already run. This property is relevant when table data is fetched in a loop configuration. In that case, this property has to be set to true. Otherwise, the subsequent response would overwrite the previous response, and all responses except the last one would be lost.	`RESTCall.LoadRowsNow = true`
NextRequest	Initialization script, Response script	Can be set to the Scripting ID of the Call REST request that should be executed next.	`RESTCall.NextRequest = "CreateInvoice"`
ExecCounter	Initialization script, Response script	Counts the number of times a certain Call REST request was subsequently executed. Calling a different request resets the counter. In combination with NextRequest this property can be used to build loops.	`RESTCall.ExecCounter = 3`
ExitSuccess	Response script	Exits the configured Call REST request sequence immediately, even if further requests are configured in the sequence.	`RESTCall.ExitSuccess()`
ScriptError	Response script	Forces an immediate error termination of the configured Call REST request sequence. The provided error message string is used in the error event.	`RESTCall.ScriptError("...error text...")`
StatusCode	Response script	Returns the HTTP status code of a REST call.	`RESTCall.StatusCode`
Url	Initialization script	Allows configuration of a Call REST URL via scripting. Overrides the Url configured in the configuration dialog.	`RESTCall.Url="https://example"`

BodyJSONContent sample script

This sample script converts invoice data to a JSON string and sends it as the body of the REST call.

Copy

function InvoiceW(inv) {
  this.inv = inv;
}

function Invoice(no, date, amount) {
  this.no = no;
  this.date = date;
  this.amount = amount;
}

var invoice = new Invoice(IndexData.GetField("Invoice_No"),
IndexData.GetField("Invoice_Date"),
IndexData.GetField("Invoice_Amount_net"));

var inv = new InvoiceW(invoice);

RESTCall.BodyJsonContent = JSON.stringify(inv);