Interface Script Syntax

The Interface Script for a method that is running on the REST interface follows a certain syntax. Each line of the Interface Script is interpreted seperately and contains the name of an action with its value.

Actions

The following table describes the actions that can be used in the Interface Script.

Action name	Required?	Description
Method	required	The HTTP request method to send with the request. The interface supports the following request methods: GET POST PUT PATCH DELETE
Path	optional	The path of the endpoint. This will be appended to the url specified in the profile.
Body	optional	The data to send with the request. This can be either a JSON string, a URL query string or a path to a file that contains the body. When this action is left empty, the input fields are mapped to their external field name equivalent and sent as a JSON object. This action is ignored for the GET and DELETE methods.
MultipartFormDataContent	optional	The content as a string to set as the multipart form data content. This string can be the local path to a file to set as the content. Only one of the two options `MultipartFormDataContent` and `MultipartFormDataContentField` can be set. If you want to include a JSON in the request body you can use the `Body` parameter in combination with this property. >This action is ignored for the GET and DELETE methods.
MultipartFormDataContentField	optional	The field containing the contents to set as the multipart form data content. Only one of the two options `MultipartFormDataContent` and `MultipartFormDataContentField` can be set. This action is ignored for the GET and DELETE methods. The following field types are supported: Media: the file is streamed and this type is preferred. Text: a path to a local file. The local file will be streamed, a base64 string in a text field is not allowed.
MultipartFormDataContentName	optional	The name of the multi part form data content HTTP content. If this is left empty and `MultipartFormDataContent` is used, `body` will be used as a default. This should be set to `file` when sending a file. This action is ignored for the GET and DELETE methods.
MultipartFormDataContentFilename	optional	The filename of the multi part form data content HTTP content. This is required when the `MultipartFormDataContentName` is set to `file`. This action is ignored for the GET and DELETE methods.
MultipartFormDataContentType	optional	The content type to set for the multi part form data content. This action is ignored for the GET and DELETE methods.
BodyMapping	optional	Whether the input fields should be mapped to their external field name equivalent and sent as a specific format. The possible options are: None: you need to map input fields in the body yourself. Json: default behaviour: input fields are sent as a JSON string in the body.
Header	optional	The request headers to send with the request. This action needs to be provided in the form of a JSON string. Authentication headers, such as a token, should be provided via this property.
ContentHeader	optional	The content headers to send with the request. This action needs to be provided in the form of a JSON string. When it is not provided, the `Content-Type` header will be set as `application/json`.
ValueProperty	optional	The path of the property holding the values you want to retrieve. If the property is a nested property, you can specify the path using a dot as separator: `result.value`. When this action is left empty, the root of the response will be considered as the values to return.
ExtendedDataProperty	optional	The name of the property in the response that contains a url to fetch extra data for the record that is being processed. Before using this action, read the performance notice further on this page.
ExtendedDataValueProperty	optional	The path of the property in the extended data result holding the values to include in the current record. If the property is a nested property, you can specify the path using a dot as separator: `extendedResult.value`. When this action is left empty, the root of the response will be considered as the values to return.
DisableStructureJsonOutput	optional	Method fields that point directly to a structure in the REST output will return the raw json as their output in Ometa. Specify `DisableStructureJsonOutput=True` to disable this.

ExtendedDataProperty

Even though we support extending the data returned by the main endpoint with a new call, you should use this with care! This will execute a request for each record that is returned by the main endpoint and thus cause a severe performance penalty. When this penalty is not bearable, consider redesigning the usage of this data or limiting the records returned by this method.

Debug

Create a local field called REST.Debug to get the complete JSON structure for debugging reasons.

Examples

The following examples use the profile for fetching TODO items from an online available REST service for testing purposes.

Getting All TODO Items

We can retrieve all the TODO items, just by using the root of the TODO items REST service. This means that we only need to specify the GET HTTP request method.

Method=Get

Field	Type	External name
User Id	Integer	userId
Id	Integer	id
Title	Text	title
Completed	YesNo	completed

Getting A TODO Item By Id

The routes specifications in the TODO items REST service specifies that a single TODO item can be fetched by using its unique identifier. We can pass this identifier to the Path action in the Interface Script using a context token and an input field.

Method=Get
Path=/todos/{$Id}

Field	Type	External name
Id	Integer	id

Field	Type	External name
User Id	Integer	userId
Id	Integer	id
Title	Text	title
Completed	YesNo	completed

Creating A New TODO Item

Using the POST HTTP request method, the interface will call the /todos endpoint with a JSON object that will be considered as the body of the call.

Method=Post
Path=/todos

The request body will be like this:

{
  "userId": 10,
  "title": "Go grocery shopping"
}

Field	Type	External name	Value
User Id	Integer	userId	10
Title	Text	title	Go grocery shopping

Updating An Existing TODO Item

Using the PUT HTTP request method, the interface will call the /todos/1 endpoint with a JSON object that will be considered as the body of the call.

Method=Put
Path=/todos/{$Id}

The request body will be like this:

{
  "id": 1,
  "userId": 10,
  "title": "Go grocery shopping"
}

Field	Type	External name	Value
User Id	Integer	userId	10
Id	Integer	id	1
Title	Text	title	Go grocery shopping

Uploading A File Using Multipart Form Data

A file can be send to a REST service using multipart form data content. This example contains multiple different approaches using the POST HTTP request method to uploading a file to a REST service: working with a media field, a text field and local path in the interface script. When working with a multi part form data content you can also use the Body parameter to send another body containing a JSON for the document metadata for example.

Dynamic Contents Using Fields

The following interface script will use the field 'File Content' as the multipart data contents, those contents will be added to the name 'file' and the filename will be set to 'File Name' field. The field 'File Content' can be a media field containing the file contents, a text field containing the local path or a text field containing the base64 string of the file.

Method=POST
Path=/files/upload
MultipartFormDataContentField=File Content
MultipartFormDataContentName=file
MultipartFormDataContentFilename={$File Name}

Field	Type	Value
File Name	Text	DemoFilename.docx
File Content	Media / Text	[File contents or local path to the file]

In our example the download URL and name of the file will be returned as a JSON by the service.

Field	Type	External name	Value
Download Url	Text	DownloadUrl	[Test REST service url]/files/uploaded/DemoFilename.docx
Name	Text	Name	DemoFilename.docx

Using Static Contents And A Content Type

The following example will upload the local file located in the local path 'c:\Template Documents\template.pdf' to the REST service using a static file name. This service requires a content type for the binary content.

Method=POST
Path=/files/upload
MultipartFormDataContent=c:\Template Documents\template.pdf
MultipartFormDataContentName=file
MultipartFormDataContentFilename=DemoFilename.pdf
MultipartFormDataContentType=application/pdf

Field	Type	Value
File Name	Text	DemoFilename.docx
File Content	Media / Text	[File contents or local path to the file]

In our example the download URL and name of the file will be returned as a JSON by the service.

Field	Type	External name	Value
Download Url	Text	DownloadUrl	[Test REST service url]/files/uploaded/DemoFilename.docx
Name	Text	Name	DemoFilename.docx

Including A JSON Body In The First Part

The following example will upload the local file located in the local path 'c:\Template Documents\template.docx' to the REST service using a static file name. This example includes a JSON body that will be send as the first part of the multi part form data, the content type and content header can be specified using the standard BodyContentType and ContentHeader parameters.

Method=POST
Path=/files/upload
Body={"Keywords": "{$Keywords}", "Type": "{$Type}"}
BodyContentType=application/json
ContentHeader={"Content-Disposition": "form-data; name=\"entity_document\""}
MultipartFormDataContent=c:\Template Documents\template.pdf
MultipartFormDataContentName=file
MultipartFormDataContentFilename=DemoFilename.pdf
MultipartFormDataContentType=application/pdf

Field	Type	Value
File Name	Text	DemoFilename.docx
Keywords	Text	draft testing
Type	Text	PDF
File Content	Media / Text	[File contents or local path to the file]

In our example the download URL and the metadata of the file will be returned as a JSON by the service.

Field	Type	External name	Value
Download Url	Text	DownloadUrl	[Test REST service url]/files/uploaded/DemoFilename.docx
Name	Text	Name	DemoFilename.docx
Keywords	Text	Name	draft testing
Type	Text	Name	PDF

Sending A POST Request With The Body In Multipart Form Data Content

Using the POST HTTP request method, we will send the body of the request using multipart form data. This example will send JSON body as multi part form data.

We're not setting the MultipartFormDataContentName parameter as this will multipart data content will be added to the name 'body' by default.

Method=POST
Path=/workspace
MultipartFormDataContent={ "templateId": {$Template ID}, "name": "{$Name}", "parentId": {$Parent ID} }

Field	Type	Value
Template ID	Text	577527
Name	Text	Demo Workspace
Parent ID	Text	785785785

Field	Type	External name	Value
ID	Text	id	1

Retrieving The Value Of A Nested Property

Some REST services return the data we want to retrieve in a nested property instead of the root. An example of such a nested property can be a count property which holds the number of records. Using the ValueProperty action, we can specify which property holds the data we need. The same applies to match an output field with a nested property in a result record.

{
  "recordCount": 4,
  "data": [
    {
      "id": 3196,
      "title": "Go grocery shopping",
      "createdBy": {
        "name": "Awesome user"
      }
    },
    {
      "id": 3197,
      "title": "Let the dog out",
      "createdBy": {
        "name": "Less awesome user"
      }
    },
    {
      "id": 3198,
      "title": "Go to a Gotye concert",
      "createdBy": {
        "name": "Just somebody I used to know"
      }
    },
    {
      "id": 3199,
      "title": "Blame husband",
      "createdBy": {
        "name": "Mom"
      }
    }
  ]
}

Field	Type	External name
User Name	Text	createdBy.name
Id	Integer	id
Title	Text	title

User Name	Id	Title
Awesome user	3196	Go grocery shopping
Less awesome user	3197	Let the dog out
Just somebody I used to know	3198	Go to a Gotye concert
Mom	3199	Blame husband

Sending An OAuth-access Token With The Request Using the Password Flow

The password flow should only be used when it's not possible to retrieve a client id and secret from the provider. We will show you how you can use an input extension to request an access token, but this will introduce a performance penalty.

Step 1: Getting An Access Token

When using OAuth integrated security, requests may require an access token to be included in the request headers.

The method for retrieving the access tokens should not have input fields. All the required fields are specified in the REST Profile. The interface script uses the following fields:

Field	Type	Description
Profile.OAuth Client ID	External	The public identifier for the REST client
Profile.OAuth Client Secret	External	The client secret to use with the client id
Profile.Username	External	The username to authenticate against the REST client
Profile.Password	External	The password to authenticate against the REST client

Make sure the OAuth Url field is not set in the profile, as this will cause the REST interface to start a client_credentials flow.

Method=Post
Path=/oauth/token
ContentHeader={"Content-Type":"application/x-www-form-urlencoded"}
Body=client_id={$Profile.OAuth Client ID}&client_secret={$Profile.OAuth Client Secret}&grant_type=password&username={$Profile.Username}&password={$Profile.Password}

{
  "data": [
    {
      "Access Token": (Access
      Token
      string),
      "Token Type": "Bearer",
      "Expires_in": "300",
      "refresh_token": (refresh
      token
      string)
    }
  ]
}

Field	Type	External name
Access Token	Text	Access Token
Token Type	Text	Token Type
Expires In	Integer	expires_in
Refresh Token	Text	refresh_token

Access Token	Token Type	Expires In	Refresh Token
(Access Token string)	Bearer	300	(Refresh token string)

Step 2: Creating A New Item Using The Access Token

In this POST-call, the retrieved authentication token is sent with the request header. The method shown in step 1 can be used as input data extension to pass the values of the token type and access token.

The configuration for the input data extension can be done via the Advanced tab.

Method input fields:

Field	Type	Value
Title	Text	Go grocery shopping

Input extension fields:

Field	Type	Value
Token type	Text	Bearer
Access token	Text	(Access token string)

Method=Post
Path=/jsonapi/node/todos
Header={"Accept":"application/vnd.api+json", "Authorization":"{$Token Type} {$Access Token}"}
ContentHeader={"Content-Type":"application/vnd.api+json"}
Body={ "title": "{$Title}" }

The request body will be like this:

{
  "title": "Go grocery shopping"
}

Field	Type	External name	Value
ID	Integer	id	201

Access SharePoint REST API v1

Files

In the following example you will request the list items of a certain folder using the SharePoint REST API v1 on SharePoint Online.

Profile Fields
Interface Script

Field	Type	Value	Description
OAuth Url	External	https://accounts.accesscontrol.windows.net/{{AAD Id}}/tokens/OAuth/2	The URL to request access tokens. The {{AAD Id}} should be replaced by the Azure Active Directory Id.
OAuth Grant Type	External	client_credentials	The grant type which should be set to: client_credentials
OAuth Client Id	External	{{app clientId}}@{{AAD Id}}	The client id of the registered app followed by '@' and the id of the Azure Active Directory Tenant, or the farm id for your on-premise deployment. New apps can be registered in Office 365 on https://aad.portal.azure.com/
OAuth Client Secret	External	*******************	The client secret of the registered app.
OAuth Scope	External	resource;00000003-0000-0ff1-ce00-000000000000/{{domain}}.sharepoint.com@{{AAD Id}}	The resource is constructed out of {{principal}}/{{targetHost}}@{{AAD Id}} The principal can be one of the following: ACS - 00000001-0000-0000-c000-000000000000 Exchange - 00000002-0000-0ff1-ce00-000000000000 SharePoint - 00000003-0000-0ff1-ce00-000000000000 Lync - 00000004-0000-0ff1-ce00-000000000000 Workflow - 00000005-0000-0000-c000-000000000000 / The target host is the domain of the tenant like: contoso.sharepoint.com. @ The Azure Active Directory id or the farm id for your on-premise deployment.

Method=GET
Path=/_api/web/GetFolderByServerRelativeUrl('/sites/MySite/Shared Documents/MyFolder')/Files?$select=Name,Title,TimeLastModified,ModifiedBy/Title&$expand=ModifiedBy
Header={"Accept": "application/json;odata=verbose"}
ValueProperty=d.results

Move File

In the following example you will move a file using the SharePoint REST API v1.

Profile Fields
Interface Script

Field	Type	Value	Description
OAuth Url	External	https://accounts.accesscontrol.windows.net/{{AAD Id}}/tokens/OAuth/2	The URL to request access tokens. The {{AAD Id}} should be replaced by the Azure Active Directory Id.
OAuth Grant Type	External	client_credentials	The grant type which should be set to: client_credentials
OAuth Client Id	External	{{app clientId}}@{{AAD Id}}	The client id of the registered app followed by '@' and the id of the Azure Active Directory Tenant, or the farm id for your on-premise deployment. New apps can be registered in Office 365 on https://aad.portal.azure.com/
OAuth Client Secret	External	*******************	The client secret of the registered app.
OAuth Scope	External	resource;00000003-0000-0ff1-ce00-000000000000/{{domain}}.sharepoint.com@{{AAD Id}}	The resource is constructed out of {{principal}}/{{targetHost}}@{{AAD Id}} The principal can be one of the following: ACS - 00000001-0000-0000-c000-000000000000 Exchange - 00000002-0000-0ff1-ce00-000000000000 SharePoint - 00000003-0000-0ff1-ce00-000000000000 Lync - 00000004-0000-0ff1-ce00-000000000000 Workflow - 00000005-0000-0000-c000-000000000000 / The target host is the domain of the tenant like: contoso.sharepoint.com. @ The Azure Active Directory id or the farm id for your on-premise deployment.