OData

The REST interface can approach OData services like any other REST service, it has limited additional support for automatic paging and query options.

In general, we recommend using the OData interface since it has fully integrated filtering, querying and paging with ADM as well as more niche features such as request batching. But in scenarios where the external service doesn't strictly follow the protocol, or configuration proves difficult, the REST interface can be used as well.

Profile

To use OData-specific features of the REST interface: set the profile field REST Standard to OData. It can also be set for individual methods by specifying RestStandard=OData in the interface script.

If not configured, the REST interface will approach the service like any other REST service.

Paging

In OData, services may opt to use server-side paging. This is not required and depends on the service implementation. When implemented, a limited amount of records is returned rather than the full data set. This can be an arbitrarly 1000 records, or the specified $top option. The next page is made available with the @odata.nextLink attribute found in the response body. When processing a method request with the REST Standard: OData, the REST interface will automatically navigate to the next page and combine its data with the previous page(s).

Warning

Depending on the number of records in the data set, multiple requests are sent to the REST service, extending the execution time of the method. The Ometa REST interface will stop sending out requests upon reaching its requested page size from a view, however synchronizations or testing in the business connector will always request all data. To safeguard against excessive requests, we limit the number of paging requests to 100 (per context record) after which an error will be shown. This is done to preventatively stop performance issues: a likely culprit can be a page size too small, an issue with paging in the external service, or just a large amount of data. Sorting from ADM can commonly trigger this, since sorting requires Ometa to fetch all data. Consider disabling sorting on the view fields to circumvent this. This safeguard can be modified by adding an entry to the Config table: REST Page Request Limit. Setting it to a negative number will disable it entirely. The interface must be restarted for the setting to take effect.

Filtering and Sorting

There is no special support for filtering and sorting from the REST interface. As such, sorting a column will trigger the REST interface to fetch all data from all pages to then locally sort them. Consider disabling filtering and sorting on the columns of the view to prevent this.

Query Options Integration

The REST interface has the option to translate the query options from a view to OData statements. This does not happen automatically but rather through some placeholders that can be used in the interface script, identical to the ODBC Query Options.

The available options are:

Options	Placeholder	Example Interface Script	Example Resolves To
Filter	{$@ometa.filter}	/Products?\(filter={\)@ometa.filter}	/Products?$filter=Name eq 'Bike'
Sort	{$@ometa.sort}	/Products?\(orderby={\)@ometa.sort}	/Products?$orderby=Name asc
Page Size	{$@ometa.pageSize}	/Products?\(top={\)@ometa.pageSize}	/Products?$top=25
First Item	{$@ometa.firstItem}	/Products?\(skip={\)@ometa.firstItem}	/Products?$skip=0

These are also available through the context menu in the interface script.

When possible, configure all the placeholders in the interface script: /Products?$filter={$@ometa.filter}&$orderby={$@ometa.sort}&$top={$@ometa.pageSize}&$skip={$@ometa.firstItem}. When resolved, it will replace the placeholders with the values from the view.

Filtering

Filtering can be done on the ADM by clicking on the side of the header in ADM. The REST interface can interpret these filters and translate them into a OData statement, this filter can then be used in the interface script:

• {$@ometa.filter}: the OData statement equivalent to the current query options, excluding $filter= keyword.

The external name will come from the input method field if it exists, or the output method field otherwise. If no field can be found, the filtering is not forwarded and processed locally instead.

If no query options are available, or no column is sorted:

• Ometa will try to strip out the placeholder and $filter statement if possible, while leaving a valid OData url.
• If not possible,{$@ometa.filter} will default to 1 eq 1.

Query options can be missing if the method is not executed through a view, for example when testing it in the business connector, or when running as a method job. The default is provided to not require additional logic and prevent SQL syntax issues. This filter can be freely combined with other clauses.

The filtering can be used regardless of the other context fields for paging or sorting, without impacting data integrity.

The performance benefit from using this in the interface script comes from:

• The external service can optimize its query on their end.
• Ometa has less data to sift through.

There are slight differences in query translations for OData v2 and v3 compared to OData v4. If encountering issues with the filtering, verify the OData version from the metadata and specify the correct version in the profile or interface script: RestStandard=ODatav4

Example

The example is showing a combined filter, where users get to see all red coloured products and can apply additional filters through the ADM.

• Interface Script
• Contains
• Does Not Contain
• Starts With
• Ends With
• Equals
• Not Equals
• Combinations

Path=/Products?$filter=Color eq 'Red' and {$@ometa.filter}

Sorting

Sorting is applied when end users click on columns in an ADM. This context field is available to implement this:

• {$@ometa.sort}: the external name of the field to order, followed by the direction: ProductName DESC, Id ASC, excluding the ORDER BY keyword.

The external name will come from the input method field if it exists, or the output method field otherwise. If no field can be found, the sorting is not forwarded and processed locally instead.

If no query options are available, or no column is sorted:

• Ometa will try to strip out the placeholder and $orderby statement if possible, while leaving a valid OData url.
• If not possible,{$@ometa.sort} will default to 1 ASC.

Query options can be missing if the method is not executed through a view, for example when testing it in the business connector, or when running as a method job. The default is provided to not require additional logic and prevent SQL syntax issues.

The sorting can be used regardless of the other context fields for paging or filtering, without impacting data integrity.

This benefits performance because the framework does not have to process all data to sort it locally, and can stop reading once it has reached its page size.

Example

The example only does sorting through the interface script, with Company as the default sorting. Filtering and paging still works and is done by the framework locally.

• Interface Script
• One Column
• Two Columns
• No Query Options

Path=/Products?$orderby={$@ometa.sort}, Company ASC

Paging

Most views on the framework have paging enabled, these context fields are available to implement this:

• {$@ometa.firstItem}: the number of items to skip. This will be the page number * page size for the current view.
• {$@ometa.pageSize}: the numbers of items to return. This will be the page size of the view plus one to check if a next page is available.

If no query options are available:

• {$@ometa.firstItem} will default to 0.
• {$@ometa.pageSize} will default to the BCSL.BCS_OData.MaxPageSize config setting, or 1.000.000 if not configured. Changing this setting requires the process to be restarted.

Query options can be missing if the method is not executed through a view, for example when testing it in the business connector, or when running as a method job.

Important

Ometa can only forward the paging if the sorting and filtering is also forwarded. Otherwise, the data could be incorrect, since Ometa would be sorting and filtering locally on a limitted dataset. If filtering or sorting is not forwarded, or could not be parsed, paging is not forwarded either to ensure correct results.

Example

In the example, only paging was specified, there was no specific filter or sorting set. The view is configured to have page size 25.

• Interface Script
• First Page
• Second Page
• No Query Options

Path=/Products?$filter={$@ometa.filter}&$orderby={$@ometa.sort}&$skip={$@ometa.firstItem}&$top={$@ometa.pageSize}

Server-side paging

If the external REST service uses server-side paging, the Ometa REST interface will automatically process the @odata.nextLink attributes which will be sent along with the data to ADM. Depending on the service implementation, the $skip option can be left out of the interface script (for example Graph API). The $top={$@ometa.pageSize} option should still be used.