OData API in SAP Cloud Integration for Beginners

saranya_baskaran2 · ‎2019 Aug 12

This blog post covers how to expose an OData API in SAP Cloud Integration with CRUDQ operations.

Introduction

In SAP Cloud Integration, You can develop OData API that exposes existing data sources, such as SOAP, OData, ODC, and REST as OData endpoints. In this blog post, I will be exposing an existing OData Service with some modifications in SAP Cloud Integration.
Official Documentation

Prerequisite

You have to know OData protocol and how to use an OData Service for Create, Read, Update, Delete operations. Help

You have to know how to model Integration Flows and know how to use Message mappings.

You have to know the difference between OData Service project and Integration Flow with OData sender.

How to use Postman Rest client to perform HTTP calls.

What this blog doesn't cover

How to create the request payload for Create, update and $batch operations.

Help with Olingo

SAP Cloud Integration uses Olingo library to serialize/deserialize the request-response and URI.

Olingo UriInfo stores the request URI information.

This git contains java code to getUriInfo object with olingo library.

OData Receiver Service

OData Service that I will be using is the reference service from https://www.odata.org/odata-services/

https://services.odata.org/V2/(S(ODataSenderCPIDemo))/OData/OData.svc/

TIP: In the above service URL, (ODataSenderCPIDemo) represents a unique session for the manipulation of records. i.e., Entities created, updated, deleted will reflect only in that session. You can have your own session with any string within S() for your testing.

X-CSRF-Token support

OData API exposed is CSRF enabled. SAP Cloud Integration expects its clients to send a valid CSRF token in the HTTP header X-CSRF-Token with every request, except for

GET

If you don't, you will receive an error response with the status code 403

Fetch a CSRF-token
Send a GET-request to your service root with the appropriate Authorization header and the X-CSRF-Token header with value Fetch.

Send the CSRF-Token with every request
Now, you can send your payload-requests with the header X-CSRF-Token set to the value received in the response header of step 1. If your session or token expires, you will get a 403-error again. Just repeat the steps above.

OData Sender Behavior

OData sender converts the incoming OData Request payload (atom+xml / json) to simple XML.

For OData Operations which has response body (create, read), the final step in the IFlow has to be a simple XML which represents the Entities defined in OData sender Edmx.

The URI of the OData Sender can have OData query parametersa and other custom parameters. The URI parameters have to be retrieved using Olingo UriInfo which is available in message header "UriInfo".

OData Sender Updates

OData sender version 1.2 onwards: Request URI, QueryString and HTTP Method are stored in exchange header CamelHttpUri, CamelHttpQuery, and CamelHttpMethod respectively. In order to get these headers, it has to be added in 'Allowed Headers' in integration flow Runtime configuration as below.

The exception message will not be returned to the client. Refer KBA

1. Create an OData API Artifact

Create an OData Sender project by following the documentation up to step 7.

Download the metadata from existing OData service from postman
https://services.odata.org/V2/(S(ODataSenderCPIDemo))/OData/OData.svc/$metadata
TIP: Use your own session

Open the created artifact in Edit mode, choose Import Model Wizard

Select Data Source Type as ODATA, Browse the Edmx file saved in step 2

Choose the entities that you want to expose in the API from SAP Cloud Integration. I have chosen Products and Suppliers (without Address fieds)

Choose the fields that will be key in each entity. I have chosen ID and ReleaseDate to be the Key of Products.

Click Finish.

Now the OData Service is ready with no operations configured. In order to deploy an OData API, at least one operation has to be configured. Click on bind link under Actions.

Choose the Entity and the End Point to your OData Receiver Service.

An Iflow template for OData Read operation will be generated. Now the OData Service is ready for Deploy.

2. Deploying an OData API

Deploy the service by following the documentation.

On the Endpoints tab, you can view the endpoint URI. This endpoint URI is the OData Service Root URI.

3. Invoking an OData API

Copy the endpoint URI by choosing the copy icon.

From Postman, fire the request for the endpoint with the user having the role ESBMessaging.send

The OData API has 2 entities ProductSet and SupplierSet. Copy the EDMX URL and trigger it from Postman.
The OData Receiver Service had Products and Suppliers, which is exposed in SAP Cloud Integration as ProductSet and SupplierSet. Similarly, you can see that the ProductSet has 2 Key property that was configured previously.

4. Editing an OData Model

Follow the steps from the documentation.

Rename the ID of ProductSet to ProductID and ID of SupplierSet to SupplierID.

Save and deploy. $metadata call will reflect the changes.

The following operations are supported when developing an OData service in the SAP Cloud Integration. Let's configure and test each operation one by one.

5. Read

Configure the Read operation for ProductSet. In Configure OData Data Source, make sure to give the same endpoint for all operations (with the same session)

Navigate to IFlow Editor.

A predefined IFlow will be created. The script step of the IFlow will have the template to add $top and $skip to add to message header "odataURI".

Modify the groovy script to set the key parameter as message header with key "Key_<propertyName>"
The URI parameters has to be retrieved using Olingo UriInfo which is available in message header "UriInfo".

This git contains java code to get UriInfo object. Since you cannot debug a script, you can use the java class to understand the UriInfo and derive the key property values from request URI.

import com.sap.gateway.ip.core.customdev.util.Message;

import java.util.HashMap;

import org.apache.olingo.odata2.api.uri.UriInfo;

import com.sap.gateway.ip.core.customdev.logging.*;

def Message processData(Message message) {

	def uriInfo = message.getHeaders().get("UriInfo");

    	def keyPredList = uriInfo.getKeyPredicates();				

		def k=0;

		for(item in keyPredList)

		{			

			message.setHeader("Key_"+item.getProperty().getName(),item.getLiteral());

		}

	return message;

}

The Receiver OData is configured to get the key value from the header set from the script.

The Response from OData receiver has to be mapped as per the entities in sender Edmx.

Perform the Read request from postman https://<serviceRoot>/ProductSet(ProductID=1,ReleaseDate=datetime'1995-10-01T00:00:00')

5.1 Read with Navigation

Edit the OData Model such that ProductsSet has navigation to SupplierSet and vice versa.

<edmx:Edmx

    xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx"

    xmlns:sap="http://www.sap.com/Protocols/SAPData" Version="1.0">

    <edmx:DataServices

        xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0">

        <Schema

            xmlns="http://schemas.microsoft.com/ado/2008/09/edm" Namespace="S1">

            <EntityContainer Name="EC1" m:IsDefaultEntityContainer="true">

                ....

                <AssociationSet Name="Products_Supplier_Suppliers" Association="S1.Product_Supplier_Supplier_Products">

                    <End Role="Product_Supplier" EntitySet="ProductSet"/>

                    <End Role="Supplier_Products" EntitySet="SupplierSet"/>

                </AssociationSet>

            </EntityContainer>

            <EntityType Name="Product">

                .....

                <NavigationProperty Name="Supplier" Relationship="S1.Product_Supplier_Supplier_Products" FromRole="Product_Supplier" ToRole="Supplier_Products"/>

            </EntityType>

            <EntityType Name="Supplier">

                .....

                <NavigationProperty Name="Products" Relationship="S1.Product_Supplier_Supplier_Products" FromRole="Supplier_Products" ToRole="Product_Supplier"/>

            </EntityType>

            <Association Name="Product_Supplier_Supplier_Products">

                <End Role="Product_Supplier" Type="S1.Product" Multiplicity="*"/>

                <End Role="Supplier_Products" Type="S1.Supplier" Multiplicity="0..1"/>

            </Association>

        </Schema>

    </edmx:DataServices>

</edmx:Edmx>

The navigation ProductsSet to Supplier is of cardinality * to 1. Hence the request ProductSet(ProductID=1,ReleaseDate=datetime'1995-10-01T00:00:00')/Supplier will trigger the Read operation of SupplierSet. Configure Read for SupplierSet with the initial script containing the below code.

import com.sap.gateway.ip.core.customdev.util.Message;

import java.util.HashMap;

import org.apache.olingo.odata2.api.uri.UriInfo;

import com.sap.gateway.ip.core.customdev.logging.*;

def Message processData(Message message) {

	def uriInfo = message.getHeaders().get("UriInfo");        

	def keyPredList = uriInfo.getKeyPredicates();				

		def k=0;

		for(item in keyPredList)

		{

			log.logErrors(LogMessage.TechnicalError, (++k) + " Key Predicate value for property "+item.getProperty().getName()+" is: "+ item.getLiteral());

			message.setHeader("Key_"+item.getProperty().getName(),item.getLiteral());

		}	

	def targetEntityName = uriInfo.getTargetEntitySet().getName();

	def startEntityName = uriInfo.getStartEntitySet().getName();	

	//Handle Navigation request

	if(!targetEntityName.equals(startEntityName)){

	    log.logErrors(LogMessage.TechnicalError, "Navigation request from source "+ startEntityName + " to target " +targetEntityName);

	    //Do your own processing to decide which Supplier ID to retrive.

	    message.setHeader("SupplierID","0");

	}else{

            //Handle SupplierSet Read

        }

	return message;

}

TIP : In the script above, log.logErrors are used to print the values of my variable in logs. These logs appear in System Log file of type CP default trace as below.
.....[Gateway][TECHNICAL][TechnicalError]:Entity Name::CategorySet|

Do the required response mapping. The navigation query from postman https://<serviceRoot>/ProductSet(ProductID=1,ReleaseDate=datetime'1995-10-01T00:00:00')/Supplier will return Supplier of ID 0.

6. Query

Add the initial script step to hold the query options Filter, top, skip, orderby, expand as below. Query options are retrieved using Olingo UriInfo which is available in message header "UriInfo".
[OR]
Refer point 1 in OData Sender Updates to get the query option.
$select, $count doesn't need to be handled in the script. This git contains java code to get UriInfo object. Since you cannot debug a script, you can use the java class to understand the UriInfo and derive each of the OData query options like $top $filter.

import com.sap.gateway.ip.core.customdev.util.Message;

import java.util.HashMap;

import org.apache.olingo.odata2.api.uri.UriInfo;

import com.sap.gateway.ip.core.customdev.logging.*;

def Message processData(Message message) {

	def uriInfo = message.getHeaders().get("UriInfo");

	def odataURI = new StringBuilder();

	def urlDelimiter = "&";

	def urlConcat = "?";

	def entityName = uriInfo.getTargetEntitySet().getName();

	log.logErrors(LogMessage.TechnicalError, "Entity Name::"+entityName);

	if (uriInfo.getTop() != null){

		def top = uriInfo.getTop();

		if(odataURI.size()!=0)

			odataURI.append(urlDelimiter);

		odataURI.append("\$top=").append(top);

		log.logErrors(LogMessage.TechnicalError, "Top value:"+top);

	}

	if (uriInfo.getSkip() != null){

		def skip = uriInfo.getSkip();

		if(odataURI.size()!=0)

			odataURI.append(urlDelimiter);

		odataURI.append("\$skip=").append(skip);

		log.logErrors(LogMessage.TechnicalError, "Skip value:"+skip);

	}

	if(uriInfo.getFilter() != null){

	    def filterValue = uriInfo.getFilter().getUriLiteral();

	    filterValue = filterValue.replace("ProductID","ID");  //The receiver has property names as ID and not ProductID

	    if(odataURI.size()!=0)

			odataURI.append(urlDelimiter);

		odataURI.append("\$filter=").append(filterValue);

	    log.logErrors(LogMessage.TechnicalError, "Filter value: "+filterValue);

	}

	if(uriInfo.getOrderBy() != null){

	    def orderBy = uriInfo.getOrderBy().getExpressionString();

	    if(odataURI.size()!=0)

			odataURI.append(urlDelimiter);

		odataURI.append("\$orderby=").append(orderBy);

	    log.logErrors(LogMessage.TechnicalError, "orderby value: "+orderBy);

	}

	if(uriInfo.getExpand() != null){

	    def expandList = uriInfo.getExpand();

	    def expandValue;

	    log.logErrors(LogMessage.TechnicalError, "expandList size: "+expandList.size());

	    if(expandList.size()!=0){

			odataURI.append(urlDelimiter);

    		for(item in expandList){

    		    if(item.size() > 0){

    		        for(navSegments in item){

    			            expandValue = navSegments.getNavigationProperty().getName();  //TO DO : Multiple expand values to be handled

    		        }

    		    }

    		}

    		odataURI.append("\$expand=").append(expandValue);

	        log.logErrors(LogMessage.TechnicalError, "expand value: "+expandValue);

	    }

	}

	log.logErrors(LogMessage.TechnicalError, "URI value:"+ odataURI.toString());

	message.setHeader("odataEntity",entityName);

	message.setHeader("odataURI",odataURI.toString());

	return message;

}

The receiver OData has to be configured to get the system query option from the header ${header.odataURI}

Map the response from receiver to Sender Edmx. For $expand scenario the expanded entity has to be mapped. The Response mapping template will generate source and target with only root entity.
I have created the XSD for source and target containing the Supplier child and used that XSd for the mapping.
TIP: You can use the OData receiver query modeler to generate the XSD. For the XSD to have Entity and its navigation, choose 'Create' with sub levels.

From Postman, perform Query with various query options like $select, $top, $skip, $filter, $expand.

To enable serverside pagination with next link in response, set the message header 'skipToken' with the number of records that have been returned. Eg, skipToken : 20 will add the next Link in response as <link href="Products?$skiptoken=20" rel="next"/>

$inlinecount=allpages will return the count in response only if the message property InlineCount is set with an Integer value.

7. Create

The Response of Create should have a response body of the created entity with the key properties.

Configure create for ProductSet.

Request from the Sender has to be mapped to the Receiver edmx.

Response from the receiver has to be mapped to Sender Edmx.

Perform Create operation from postman

7.1 Deep Insert

The Response of Deep Insert should have a response body with only the root Entity and not the navigation entities.
UPDATE: Software increment 2101 allows deepinsert response body to have navigaton entities too. You have to map the response structure with the root entity and the navigation entity.

In case of deep insert, the sender generates the nested structure of the deep insert payload and the same has to be handled in the iflow as per the use case.

The request mapping with nested Supplier has to be done.
Refer this blog for detailed steps to get the XSD.

The response of the deep insert should have only the root entity for the OData sender. Please note in below response mapping, only the root Entity ProductSet is mapped.

The OData deepinsert request will be converted to XML by OData sender whcih has to be handled as per your business logic.
I have enabled trace and triggered deepinsert and the equivalent XML is as below.

Since the OData receiver is capable of handling the deep insert, I have just mapped the incoming payload to the receiver as shown in step 2.

DeepInsert triggered from the postman.

I verify that the Supplier with SupplierID 6543 is created by querying on the OData receiver URL configured.
https://services.odata.org/V2/(S(ODataSenderCPIDemo))/OData/OData.svc/Suppliers(6543)

8. Update

URI handling: Similar to Read operation, The ID has to be correctly passed to the receiver.

Payload: The request payload has to be mapped just like Create.

9. Delete

URI handling: similar to Read operation, The ID has to be correctly passed to the receiver.

The is no need for request and response mapping.

10. FunctionImport

Edit the Iflow model to have a FunctionImport defined. I have defined GetProductsGTRating which will fetch all the Products greater than the rating given in input.

Configure the FunctionImport.

Modify the initial script step to store the function import parameters into the message header.

import com.sap.gateway.ip.core.customdev.util.Message;

import java.util.HashMap;

import org.apache.olingo.odata2.api.uri.UriInfo;

import com.sap.gateway.ip.core.customdev.logging.*; 

def Message processData(Message message) {

	def uriInfo = message.getHeaders().get("UriInfo");	

	def funcImpParams = uriInfo.getFunctionImportParameters();

	if(funcImpParams  != null && !funcImpParams.isEmpty()){

	    log.logErrors(LogMessage.TechnicalError, "FunctionImport"+funcImpParams);

	    def k=0;

		for(item in funcImpParams)

		{

			log.logErrors(LogMessage.TechnicalError, "Functionimport Param "+(++k)+" : "+ item.getKey()+" = "+item.getValue().getLiteral());

			message.setHeader(item.getKey(),item.getValue().getLiteral());

		}

	}

	return message;

}

Model the Iflow to handle the defined function Import. The OData receiver is configured to get all the Products with rating greater than the header value 'rating'.

Do the required response mapping.

Trigger the functionimport from the postman, <service root>/GetProductsGTRating?rating=2.
The response will contain all the Products with rating greater than 2.

11. Set Custom Error Code and Response Body for Error

The exception message will not be returned to the client. Refer point 2 in OData Sender Updates .

Perform a Create operation on ProductSet without the Key Property in payload as below.
```
{

	"ReleaseDate": "/Date(694224000123)/",

	"Rating": 4,

	"Price": "2.5"

}
```

Below is the response that will be seen.500 status code with default error.

This response can be customized with custom response code and response message.

Add an exception subprocess in create Iflow. Add a content modifier.

Set the message header "CamelHttpResponseCode" to the status code you want to propagate to Sender.

Save and deploy the artifact and trigger the create operation again. The status code will be 400 instead of 500.

The Iflows resources has an XSD named Error. Set the message body with the error message as per the XSD.

Trigger the create without key property. The response will be custom status code and message set in exception subprocess.

OData Sender related blogs

Introduction to Creating OData Service in HANA Cloud Integration

OData Service Project vs Integration Project when to use what in Cloud Platform Integration

OData Service in $batch Mode

https://blogs.sap.com/2016/06/10/deep-insert-suport-in-odata-provisioning-in-hci/

https://blogs.sap.com/2017/06/05/cloud-integration-how-to-setup-secure-http-inbound-connection-with-...

https://blogs.sap.com/2017/07/17/odata-service-project-vs-integration-project-when-to-use-what-in-cl...

https://blogs.sap.com/2018/09/16/sap-cloud-platform-integration-odata-v2-conditional-update/

former_member323756 · ‎2020 Sep 29

Hello Saranya,

Thank you so much for this blog.

We are getting 400 Bad request error in CREATE operation when we are sending a field in request payload which has property creatable="false".

The error can be elaborately seen as a attachment ODataV2_Adapter_Response_Body when we enable the traces.

But this error needs to be sent back to the requesting client. Could you please guide how should we achieve that.

Regards,

Shikha

former_member693988 · ‎2021 Mar 11

Hi Saranya ,

Is it possible to use in the same scenario an OData that comes from ECC System ?

The big picture is to receive some information saved in a custom table in ECC System to the mapping process inside the iFlow .

Best regards

Arnold

former_member1413 · ‎2021 Mar 30

Hi

I have done message mapping even then system is not considering it as deep insert . How to solve this issue ?

Regards

Tisha

former_member1413 · ‎2021 Mar 31

Hi ,

How to handle this in message mapping ?

"The Response of Deep Insert should have a response body with only the root Entity and not the navigation entities"

Regards

Tisha

former_member1413 · ‎2021 Mar 31

Hello jenibalet_s

I am also facing same issue . Were you all to solve this issue and how ?

Regards

Tisha

kuhlmanndo · ‎2021 Apr 07

Hi all & saranya.baskaran2 ,

I've got a problem with the $count parameter. The iFlow runs for several minutes since it caches all the values of the EntitySet and does the "count" only after getting all the entries and thus having a massive payload. Is this working as designed or might I have a configuration error within my iFlow? I've got the header ${header.odataURI} in the query options. The odataURI ist not filled with the $count parameter.

The blog states "$select, $count doesn’t need to be handled in the script." but does it mean that it needs to catch all entries of an odata entity and send them to CPI before counting?

BR,
Dominik

Andy1 · ‎2021 May 26

Hi saranya.baskaran2

Thank you for sharing.

BR

Afsal · ‎2021 Sep 07

Hi saranya.baskaran2

I am trying to expose my existing OData service as API following this blog (Using a Trial account).
Unfortunately, when I am trying to access the API portal, the screen showing as

"Your account is being provisioned. Please wait"

Even after 2 days, still, I am getting the same message and busy loader.

The blog I followed to set up integration suite in my Trial account: https://developers.sap.com/tutorials/cp-starter-isuite-onboard-subscribe.html

Any suggestions or help are appreciated.

dineshhome1361_7 · ‎2021 Sep 20

Hi Saranya,

Could anyone please let us know the exact URL you configured for READ and create operations please if the get operation is working?

I'm trying to execute UPDATE and POST method for API but getting 405 error https://services.odata.org/V3/Northwind/Northwind.svc/Products

Could you let me know how to pass the ID while executing?

Thanks,

Dinesh

cfewfwdwd · ‎2022 Feb 22

Hello Saranya,

thank you for providing this great blog post.

I am trying to create an ODATA API in the Cloud Integration using SOAP as data source.

I am facing with the issue that I can not find UriInfo in the message headers and therefore I can not use your script to get UriInfo object. When tracing my request, I get the following headers back:

Looking forward to your help.

Best regards,

Timo

former_member721185 · ‎2022 Apr 28

How is the $format handled in the query section? even though it is not mentioned in the script, it works when tested.. But how?

SATHEESHKUMAR_1 · ‎2022 Nov 23

Hi Saranya,

I`m not able to generate an OData flow in integration suite. Metadata are loaded correctly, I`m able to select Entity Set within the new Binding (simple Query), but when pressing OK to generate flow error message "Unable to generate integration flow" is thrown and I`m not able to continue. Does anyone else noticed similar issue?

Thank's

sting_shi · ‎2022 Nov 25

Greate blog!

Keerthana · ‎2023 Jan 13

Hi saranya.baskaran2 ,

I don't want to keep the mapping generated in the iFlow but when i am removing it,its throwing me error like "Entity Set not found in the edmx".What should i do to resolve the error?

It would be really great if anyone could help me with this.

Thanks & Regards,
Keerthana

Keerthana · ‎2023 May 05

Hi saranya.baskaran2 ,

How to enable inline count query in the odata.Please help me with this.

Regards,
Keerthana

sinhasouvik · ‎2023 May 22

Need some code adjustment in groovy, then it will work fine. Hope you had fix the issue already.

Regards,

Souvik

sinhasouvik · ‎2023 Jul 31

Hello saranya.baskaran2 ,

Hope you are doing good.

Thanks for sharing the details blog. I have couple of queries for SuccessFactors related Integration use cases.

Q1. Is it a good options to expose the SuccessFactors ODATA API using ODATA API flow in CPI? If yes is it possible to use Server Snapshot based pagination instead of client side pagination?

Q2. How to read parameters like: paging, customPageSize, fromDate, toDate query parameters for SF Integration use cases.

Expecting a response from you.

Regards,

Souvik