How to use SAP ODATA in OutSystems

SAP-OutSystems Packages Support and Upgrades
BAPI vs ODATA
SAP-OutSystems Packages Economy of Scale benefit
SAP Business API HUB
SAP-OutSystems focus on most important Business Requirements
How to use SAP ODATA

If you are considering implementing new software to support or enhance your business processes running in SAP ECC, SAP S/4HANA or SAP Hybris, you need to set up integrations with your SAP instances. You can do this by discovering and consuming the SAP digital content, like APIs, pre-packaged integration content and sample apps from the SAP API Business Hub.

SAP API Business HUB comes packed with APIs to create, update or read their information from SAP. There are also APIs available for analytics, successfactors, C/4HANA and of course S/4HANA. Interested in an API to connect to OutSystems, but wondering if it will work? Try it out   Interested in an API to connect to OutSystems, but wondering if it will work? Try it out first. Use a SAP Sandbox with standard data to test the API, and if the API meets your requirements, then go ahead and consume it. You could also test the API in a productive environment. For more information, look at Trying Out APIs.  B-Synergy has 10 years of experience building SAP-OutSystems solutions. And we rigourously test API's in order to connect to OutSystems or other Non-SAP tools. For more information contact B-Synergy

To ODATA or NOT to ODATA, that's the question
 
 The main thing OData gains over BAPIs are flexibility, open standards, and machine-readability. This may come at the price of speed.
This comparison is slightly off. While BAPI was invented to connect servers, OData is rather used to connect servers to clients. Even though OData's inventors may have had server connections in mind, pure REST has become the de facto standard for connecting this level. It would therefore be cleaner to compare BAPI to REST, and maybe related standards such as web services.

From a functionality point of view, a BAPI can be more specific and tailored to your use case than an OData data source. But OData is a standard, which means you get lots of tooling during client development for free, for instance an OData js client library. You can use frameworks that can use OData data sources, instead of programming against the individual BAPIs you made or SAP provides.

Client developers may not be familiar with the intricacies of each and every subsystem they have to fetch data from. You have the business knowledge you need to take care of and the technical dependencies that have to be met. You could expose a set of standard BAPIs to get to a similar point (if you ignored everything that isn't SAP), but OData is just that. A standard interface where at least the technical part is shared between data sources.

Whether you see the value in OData depends on where you come from. If your requirement is to develop a single, highly focused client application in OutSystems that reads and writes data from and to a SAP system, BAPIs may very well be the easiest choice. But if you have to setup some kind of CEO dashboard that integrates multiple data sources and displays all kinds of operational statistics, like sales data, production interruptions, cash flow and whatever else you may come up with, you'll have an easier time integrating OData data sources.

From a Developer Experience standpoint the SAP .NET connector provided by SAP, as implemented on OutSystems is far easier to use than the procedure for ODATA as described in this page..

How To Try Out APIs

Using the Configure Environment feature, SAP API Business Hub allows you to try out APIs against data contained in your licensed productive, test, or trial environments.

Prerequisites

-You must be logged on to SAP API Business Hub.

-The API definition file (OpenAPI specification) must contain at least one API endpoint defined under x-servers section, and a security scheme (if the API is protected by any security) is defined under securityDefinitions section.

-You have applied the security scheme to the API using the security property.

-For the Configure Environment feature to work, the URLs that you specify under x-servers must be accessible over the internet. SAP API Business Hub is an internet-facing website. Hence, you must ensure that connectivity or traffic is allowed from SAP API Business Hub to the URLs of your tentant's licensed productive or test systems.

Create a new Module

You should isolate the consumed service in a separate module, created for this specific purpose, according to the following guidelines:

If you only use the service in Reactive Web and Mobile Apps, create a "Library" module.
If you need to use the service in a Traditional Web App, create a "Service" module.
Create a service from the specification
In Service Studio, consume the service using the JSON Swagger specification file you previously downloaded.

Do the following:

1)In the Logic tab of your module, right-click the REST element under Integrations (not the SAP element) and choose Consume REST API...

2)Choose the Add All Methods option. 

3)Click Choose a File, select the specification file you downloaded previously, and click Finish.

Note: A service specification in SAP may contain attributes with several types (example: Text, Integer, and Null), but this is not supported in OutSystems. In this case, the platform assumes the most permissive type for these attributes and shows a warning message about these changes. 
If this warning message appears, close it to proceed.

How to Consume an SAP ODATA Service
 

To consume an SAP OData service in OutSystems you need to:

1)Obtain the service specification file from SAP API Business Hub
2)Consume the service in Service Studio
3)Make some final adjustments
This dpage goes through each of these tasks.

Here, in the OutSystems Forge, you can find a sample implementation of the tasks described in this topic.

Obtaining the service specification

Steps to obtain the service notifications are following: 

In the first step, you must identify the service you want to consume and download the service specification.

Do the following:

1)Open the SAP API Business Hub.


2)Search for the service in the search box.
In the example presented in this guide, we are using the "Product Master - Create, Read, Update, Delete" service from SAP S/4HANA Cloud.

3)Click the service name to go to the service page and then navigate to the Details tab.

4)Click Download Specification and select the JSON option, since Service Studio supports creating services from JSON Swagger file specifications.
Note: To download the specification, you must sign in to your SAP account.

Making some final adjustments


Handling parameters containing a dollar sign ($) in its name

In the OData standard, GET methods returning lists of records have input parameters with reserved keywords, starting with a dollar sign ($). Those input parameters are:

$select
Allows you to define which fields we want the API to return. You'll probably want to delete this input parameter since OutSystems doesn't support dynamic output structures.
$orderby
Lets you specify the fields you want to use to sort the result set.
$filter
Allows you to filter the result set by specifying conditions in the format defined in section "10.2.3.1. The $filter System Query Option" of the OData specification.
$expand
Allows you to expand child entities.
$inlinecount
The automatically generated structures do not take into account this inline count attribute. You can delete this input parameter.
$skip
Allows you to skip a certain number of results at the beginning of the result set.
$top
Allows you to define the maximum number of records in the result set.
Due to encoding issues, any outgoing requests made to the service do not include the "$" (dollar sign) character for these input parameters. You can overcome this issue by using an "OnBeforeRequest" handler. For more information on these handlers, check Simple Customizations.

To create the "OnBeforeRequest" handler do the following:

In Service Studio, select the tree element under the REST folder that corresponds to the imported service.

Add an "OnBeforeRequest" handler to your consumed service by setting the property "On Before Request" to New OnBeforeRequest.
Open the "OnBeforeRequest" callback action, now available under the REST API element, to define its flow.

In the "OnBeforeRequest" handler do the following:

1)Create a copy of the URL query parameters list.
2)Iterate through all the URL query parameters in the new list using a For Each.
2.1)For each element, check if the query parameter matches one of the reserved names (minus the dollar sign).
2.2)If it matches, add a "$" (dollar sign) at the beginning of its name.
For example, if we found a URL query parameter named "top" we would add a "$" at the beginning of its name so that it would become "$top".

Implementation example:
Adding required headers to the requests
SAP OData services require two additional headers on each request to indicate the type of content of the request body as JSON and to ask for the same content type in the response. Add these headers to the "OnBeforeRequest" handler that you created previously to handle "$" characters in parameter names.

Do the following:

1)Add a local variable with "HTTPHeader" data type to the "OnBeforeRequest" handler.

Note: The "HTTPHeader" data type is a structure that was created by OutSystems when you consumed the SAP service in Service Studio.

2)Assign the following values to the "Name" and "Value" attributes of the local variable using an Assign element:

<LocalVariableName>.Name = "Accept"
<LocalVariableName>.Value = "application/json"

3)Add this HTTPHeader structure to the headers list of the request (i.e. the "CustomizedRequest.Headers" list) using the ListAppend server action.
Repeat the two previous steps to add another HTTP header with the following "Name" and "Value". You should reuse the same local variable.

<LocalVariableName>.Name = "Content-Type"
<LocalVariableName>.Value = "application/json"

Example implementation of adding the two headers:
How to Handle data errors
In most cases, OutSystems creates an error structure for data errors when importing the service specification. This is the structure that the service returns when there's an error while fetching, updating, or inserting data. Start your error handling logic by trying to parse the error response into this data error structure.

Do the following:

1)In Service Studio, identify the structure used for data errors. This structure is available in the Data tab, in the Structures folder, under the element tree with the name of the service.
In our example, the error structure is called "error".
2)In your error parsing logic (the "Parse_ErrorResponse" action in our example), try to deserialize the response text into this error structure.

3)If the resulting structure has a text value for the error message, throw an exception with that value.
How to Handle fault errors
In fault errors like authentication errors or unexpected errors, the error response has a different format. If the error response is not a data error, try to parse the response text into the fault error structure next.

Do the following:

1)Create a structure from a sample fault error response by right-clicking the Structures tree element and then selecting Add Structure from JSON... option.

2)In your error parsing logic (i.e. in the "Parse_ErrorResponse" action in our example) add logic to parse the response text into this fault error structure.

3)If there's a "faultstring" value defined in the structure, throw an exception with the text of this element.
How to Handle API errors
1)Create a structure from a sample API error response by right-clicking the Structures tree element and then selecting Add Structure from JSON... option.

See API error example in the above picture;

2)In your error parsing logic (i.e. in the "Parse_ErrorResponse" action in our example) add logic to parse the response text into this API error structure.

3)If there's a "message" value defined in the structure, throw an exception with the text of this element.

Implementation example:
Click here to see your activities