Table of Contents

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:
  • 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.

Primary Key in Request Body

By default, the OData interface will only use the primary key for the request url and exclude it from the request body. However, for PUT requests, services can require the primary key to be repeated in the request body. If this is required, the OData interface can do this by specifying the following in the interface script:

RepeatKeyInBody=True

Query Options

The OData interface optimizes filtering, sorting and paging by appending these options to the request following the protocol. For example, sorting a column in ADM will append $ordery=columnname to the request Ometa sends out to the external OData service. This is beneficial for performance since sorting, filtering and paging is done on the external OData service side which directly returns the expected results.

However, not all OData services implement all query options. Requesting an option that is not supported by the service will return an error. To resolve this, the option LocalODataQueryOptions= can be used to force query options to be processed locally instead. Keep in mind that this often comes with a performance penalty, especially when filtering or sorting, since the framework has to fetch all available data to apply the filters.

We recommend only specifying this option if the service does not implement it.

The following options are available:

Description Interface Script OData Option Result
Sorting LocalODataQueryOptions=Order $orderby Ometa will fetch all data regardless of paging, and sort the data locally.
Select LocalODataQueryOptions=Select $select Ometa will not specify the $select option.
Filter LocalODataQueryOptions=Filter $filter Ometa will fetch all data regardless of paging, and sort the data locally.
Top LocalODataQueryOptions=Top $top Ometa will keep reading data until this number of records is found.
Skip LocalODataQueryOptions=Skip $skip Ometa will keep reading data until this number of records is skipped locally, and then process the rest of the data.
All LocalODataQueryOptions=All All of the above Ometa will not forward any query options to the external service, but keep reading data until the query options are satisfied.
None LocalODataQueryOptions=None / Default behavior, Ometa will forward all query options to the external service.

Combinations of this setting can be done by specifying it in multiple lines, or splitting by a comma. The settings will be combined, the order does not matter. For example: LocalODataQueryOptions=Skip, Top, In this case neither $skip nor $top will be forwarded to the OData service.

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.