Interface Script Syntax

In this article you can find all possible lines you can include in the interface script.

When running through the Reading Data, we use the OData Interface Wizard. This wizard composes the interface script for us. To retrieve a single row or modify data we need to change the interface script manually since this is not yet supported.

Required Actions

Interface script for a multiget method

Service Url: This is the url of the OData service to retrieve or modify data from. This line can be completely removed if the URL is specified in the profile.
Entity Set: The entity set we need to retrieve or modify data from.
Operation: The following options are possible here:
- MultiGet: Retrieve multiple rows.
- SingleGet: Retrieve a single row using a key field.
- Insert/Create: Add a new row.
- Update/Modify: Modify a row.
- Remove/Delete: Delete a row.
- Custom actions and functions defined on the entity set.
Headers: The request headers to send with the request. This action needs to be provided in the form of a JSON string. This is optional and can also be configured in the profile. If the same header is configured here and in the profile, the value from the interface script will be used.

Custom Query Options

Custom query options can be applied on the request by using Custom Query Options=[query options string].

Custom Query Options=region=5

Note

Custom query options in the interface script will be appended to the global custom query options specified in the profile (if any). If, for example, the profile contains language=en&country=UK, the resulting request will contain language=en&country=UK&region=5 as the custom query options string.

Filter

You can also specify a filter in the interface script by using Filter=[OData filter expression].

Filter=contains(Name, 'International')

This filter action can be applied on the operation MultiGet, Update/Modify and Delete/Remove. If specified on an update or delete operation multiple rows can be updated/removed.

For all possible OData filter expressions you can find more information in the OData documentation.

DisableEscapeCharsForFields

You can also specify which fields should not have their special characters (' and /) escaped for the OData call in the interface script by using DisableEscapeCharsForFields=[Field Names]. Multiple fields can be specified by using ';' in between them like the code below.

DisableEscapeCharsForFields=Name;Description

This will make sure that if there is a single ' or \ in the field value, it will stay that way and not be replaced by '' or \.

Conversion Scripts

If a field is used as Filter for example, but that specific field has a conversion script that uses another field for the search value, both fields will not be escaped in the OData call. An example of this can be found below.

Interface Script

Conversion Script

In the example, the OData filter is set to the field 'Filter'. The field 'Filter' has a conversion script that uses the 'FilterValue' field as the search value. This means that both the 'Filter' and 'FilterValue' values will not be escaped since the 'Filter' field is defined in the 'DisableEscapeCharsForFields' option. When

If the 'FilterValue' should still be escaped, you need to add the replace code to the conversion script of the 'Filter' manually.

Conversion Script

var filterValue = ({$FilterValue}).Replace("'", "''");
filterValue = filterValue.Replace("\\", "\\\\");

Json Output on Structures

When a method field is created on a navigation property structure itself, the OData interface will return the contents of the structure as json in the method output.

This behavior can be disabled by specifying the following in the interface script:

DisableStructureJsonOutput=True

Dynamic Input from Context

By default, the OData interface will only pass on input data that is specified as an input method field. As such, any context passed along that does not have a corresponding method field, will not be used. If disabled, any context that can be matched to the OData service model is mapped. This can add unexpected context from case properties, or site context and is disabled by default for this reason.

This behavior can be overriden by specifying the following in the interface script:

OnlyMapInputFields=False

Update Method

By default, the HTTP verb PATCH is used when updating an entry (or MERGE for OData v2). If you want to forcefully set the HTTP verb to be used on updates, add the following line in the interface script. Possible values are PATCH, PUT and MERGE.

Update Method=PUT

Note

PATCH is normally not supported in OData v2. However if you define it in the interface script, it will be used thus ignoring the check if the OData version is higher than v2.

Input Mapping Behavior

The input mapping behavior setting was introduced to have more control over how the OData body gets formed, especially when using NavigateTo, Singleton or custom operations. It defines how input or context in Ometa gets mapped to the OData request body.

This setting can be configured the profile, and can be overridden per method by specifying it in the interface script: InputMappingBehavior=BestMatch

There are 3 options:

Legacy: the legacy implementation. Mapping is done based on the properties of the final Entity Set, Singleton or Operation.
BestMatch: the standard for new profiles. The most specific external name available is used per OData property / parameter, one context values can not be used for multiple OData properties / parameters.
Strict: The external name must exactly match the position of the field within the url.

Overview

Below are some examples of configurations, with the expected external name listed for each behavior. The external name mapping is always case insensitive.

Verb	Url	Description	Legacy	BestMatch	Strict	Interface Script
GET	/people('aprilcline')	Fetch person with name `aprilcline`	`Name`	`Name`	`Name`	Entity Set=People Operation=SingleGet
POST	/clients(4)/link(id=5)	Custom link action for client with Id 4 to client Id 5	Not configurable (see 1)	`Id`, `link.Id`	`Id`, `link.Id`	Entity Set=Clients Operation=Link
POST	/clients(4)/copy	Custom copy action for client with Id 4	`Id`	`copy.Id` or `Id`	`copy.Id`	Entity Set=Clients Operation=Copy
POST	/people('aprilcline')/Trips	Adding a new named trip to the person with name 'aprilcline'	Not configurable (see 2)	`Name`, `Trips.Name`	`Name`, `Trips.Name`	Entity Set=People NavigateTo=Trips Operation=Create
GET	/security/clients(4)	Fetch client with Id 4 Located in singleton `security`	`Id`	`clients.Id` or `Id`	`clients.Id`	Singleton=Security NavigateTo=Clients Operation=SingleGet
GET	/security/management/clients(4)	Fetch client with Id 4 located in navigation property `management/clients` within singleton `security`	`Id`	`management.clients.Id` or `clients.Id` or `Id`	`management.clients.Id`	Singleton=Security NavigateTo=management/Clients Operation=SingleGet
PATCH	/security/clients(4)	Update the `name` on the client with Id 4.	`Id`, `Name`	`clients.Id` or `Id` `clients.Name` or `Name`	`clients.Id` `clients.Name`	Singleton=Security NavigateTo=Clients Operation=Update

(1) This can't be configured since both the Id for the client 4, as well as the operation parameter 5 will use the same external name Id.
(2) This can't be configured since both the name of the person aprilcline, as well as the Name property of the new Trip will use the same external name Name. This would result in only trips called aprilcline.

Troubleshooting

To troubleshoot mapping for BestMatch or Strict, add Debug=Mapping or Debug=True in the interface script. This will print out the external names that were looked for while building the request. Below is a sample output for BestMatch.

DEBUG INFO:
Request Success: True
Request Exception Message: 
Queried external names for input (split by ; ):
management.clients.id;clients.id;id

This message is shown due to Debug= in the interface script, remove this line to resume regular functionality

Troubleshooting Option: Debug

To help troubleshooting, the interface script option Debug=True can be used. This will print out additional information as an error message in the results window. This includes the request and response from the service. The rest of the interface script should be kept as is. Keep in mind that this will still send out the OData requests to the service.

The following options are available:

Debug=True: all information.
Debug=Request: only the request payload.
Debug=Response: only the response from the service.
Debug=Mapping: only the external names that were queried for payload. This is only available for Input Mapping Behavior=BestMatch and Input Mapping Behavior=Strict

Multiple types can be specified, separated by a comma: Debug=Request, Response

Debug Message

Method Success: True or false if the method would have succeeded without the Debug= option.
Request Success: True if the request was successfully sent to the OData service.
Request Exception Message: Potential error received from the request.
Queried external names for input: shows a list of external names that the interface went through to form the payload.
Json Body Mapping Result: Json representation of the body that is passed to the external OData client. This can be useful to figure out why requests are getting rejected before being sent.
Request: the request payload, this does not include headers and will only be sent if the payload wasn't rejected in the first place.
Response: Response received from the service, does not include headers.