Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
saranya_baskaran2
Product and Topic Expert
Product and Topic Expert
24,245
OData V2 Receiver Adapter in SAP Cloud Integration allows various operations.



This blog covers the payload structure for various Data modification operations as below.

  1. Create

  2. Deep Insert
    2.1  Deepinsert with cardinality 1:1
    2.2  Deepinsert with cardinality 1:N

  3. Create with a Reference link

  4. Update

  5. Merge

  6. Patch

  7. Delete

  8. Batch

  9. UPSERT (Success Factors Adapter)

  10. Function Import
    10.1 Function import in $batch


 

The table below summarizes some of the primitive types and how each MUST be represented when used in a payload.












































Primitive Types Format Sample
Null xsi:nil="true" <cellPhone xsi:nil="true"></cellPhone>
Edm.DateTime YYY-MM-DDTHH:MM:SS.sss
milliSeconds upto 3 digits only considered.
1992-01-01T23:30:10.231
Edm.Boolean False
If false is provided in payload false is passed to backend. For any other value true is passed to backend.
false
Edm.Guid dddddddd-dddd-dddd-dddd-dddddddddddd' where each d represents [A-Fa-f0-9] 12345678-aaaa-bbbb-cccc-ddddeeeeffff
Edm.DateTimeOffset yyyy-mm-ddThh:mm[:ss[.fff]]
milliSeconds upto 3 digits only considered.
2018-03-04T22:22:22.123Z
Edm.String any UTF-8 character Hello World
Edm.Time 22:22:22.123


1. Create (POST)


This operation creates an entity in a collection.
The OData adapter sends a POST request to the collection's URL.
The POST body MUST contain a single valid entity representation.

Sample payload for the OData service http://services.odata.org/V2/(S(readwrite))/OData/OData.svc/

Sample payload for Create operation with Complex Property Address
<Suppliers>								//EntitySetName
<Supplier> //EntityTypeName
<ID>2000</ID> //Simple Property
<Name>KTM Supplier</Name>
<Concurrency>4</Concurrency>
<Address> //complex Property
<Street>NE 228th</Street>
<City>Sammamish</City>
<State>WA</State>
<ZipCode>98074</ZipCode>
<Country>UK</Country>
</Address>
</Supplier>
</Suppliers>

 

Sample payload for Different Edm Types
<Products>
<Product>
<ID>2000</ID> //Edm.Int32
<ReleaseDate>1992-01-01T00:00:00</ReleaseDate> //Edm.DateTime
<Rating>4</Rating> //Edm.Int32
<Price>2.5</Price> //Edm.Decimal
<DistributeDate>2017-03-04T22:22:22.123Z</DistributeDate> //Edm.DateTimeOffset
<Picture>FRwvAAIAAAAAAQUAAAAAAADHrQX+</Picture> //Edm.Binary
<Guid>12345678-abcd-bbbb-cccc-ddddeeeeffff</Guid> //Edm.Guid
<Discontinued>false</Discontinued> //Edm.Boolean
<unitsPresent>2.0d</unitsPresent> //Edm.Double
<Discount>0</Discount> //Edm.Single
<SaleStartTime>22:22:22.123</SaleStartTime> //Edm.Time
</Product>
</Products>


While creating an entity, if a property is not present in the payload then a null value is passed to the OData server.




2. Deep Insert


With Deep Insert feature product and category can be created at the same time in one activity. The navigation property defined from an entity to another entity can have different cardinalities:Deep insert is a functionality which allows the application to create single entities deeply.

  1. 1:1

  2. 1:N


While using deep insert, the data (payload) needs to be nested, i.e. a deep structure is expected.

Suppose an OData entity “Product” has navigation property to another OData entity “Category” as shown in below
<EntityType Name="Product">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ID" Type="Edm.Int32" Nullable="false"/>
<Property Name="Name" Type="Edm.String" Nullable="true" m:FC_TargetPath="SyndicationTitle" m:FC_ContentKind="text" m:FC_KeepInContent="false"/>
<Property Name="Description" Type="Edm.String" Nullable="true" m:FC_TargetPath="SyndicationSummary" m:FC_ContentKind="text" m:FC_KeepInContent="false"/>
<Property Name="ReleaseDate" Type="Edm.DateTime" Nullable="false"/>
<Property Name="DiscontinuedDate" Type="Edm.DateTime" Nullable="true"/>
<Property Name="Rating" Type="Edm.Int32" Nullable="false"/>
<Property Name="Price" Type="Edm.Decimal" Nullable="false"/>
<NavigationProperty Name="Category" Relationship="ODataDemo.Product_Category_Category_Products" FromRole="Product_Category" ToRole="Category_Products"/>
<NavigationProperty Name="Supplier" Relationship="ODataDemo.Product_Supplier_Supplier_Products" FromRole="Product_Supplier" ToRole="Supplier_Products"/>
</EntityType>

 

2.1 Deep Insert with Navigation Cardinality 1:1


With Navigation Cardinality 1:1, the payload will have following structure.

Payload structure for DeepInsert 1:1
<EntitySetName>
<EntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
<NavigationPropertyName>
<NavigationEntityName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</NavigationEntityName>
</NavigationPropertyName>
</EntityTypeName>
</EntitySetName>

 

Sample payload (with reference to http://services.odata.org/(S(lebb5euydx3m3xt5r2rqmou4))/V2/OData/OData.svc/Products)
<Products>														//EntitySetName
<Product> //EntityTypeName
<ID>10012</ID>
<ReleaseDate>1992-01-01T00:00:00.123</ReleaseDate>
<Rating>4</Rating>
<Price>2.5</Price>
<Category> //NavigationPropertyName
<Category> //NavigationEntityName
<ID>10002</ID>
<Name>Perfume</Name>
</Category>
</Category>
</Product>
</Products>

 

2.2 Deep Insert with Navigation cardinality 1: N


With Navigation Cardinality 1: N, the payload will have following structure:

Payload structure for DeepInsert 1:N
<EntitySetName>
<EntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
<NavigationPropertyName>
<NavigationEntityName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</NavigationEntityName>
<NavigationEntityName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</NavigationEntityName>
<NavigationEntityName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</NavigationEntityName>
</NavigationPropertyName>
</EntityTypeName>
</EntitySetName>

 

Sample payload for DeepInsert 1:N
<Categories>
<Category>
<Name>Detergents</Name>
<ID>123567</ID>
<Products>
<Product>
<ID>521</ID>
<ReleaseDate>2005-10-01T00:00:00.000</ReleaseDate>
<Rating>3</Rating>
</Product>
<Product>
<ID>471</ID>
<ReleaseDate>2005-10-01T00:00:00.999</ReleaseDate>
<Rating>4</Rating>
<Price>19.9</Price>
</Product>
<Product>
<ID>491</ID>
<ReleaseDate>2005-10-01T00:00:00.000</ReleaseDate>
<Rating>3</Rating>
</Product>
</Products>
</Category>
</Categories>

 

Payload structure for Deepinsert 1:N where N can be deeply inserted to another navigation property.

For example, Category has navigation to Products. Product has navigation to Supplier.
<EntityType Name="Product">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ID" Type="Edm.Int32" Nullable="false"/>
<Property Name="Name" Type="Edm.String" Nullable="true" m:FC_TargetPath="SyndicationTitle" m:FC_ContentKind="text" m:FC_KeepInContent="false"/>
<Property Name="Description" Type="Edm.String" Nullable="true" m:FC_TargetPath="SyndicationSummary" m:FC_ContentKind="text" m:FC_KeepInContent="false"/>
<Property Name="ReleaseDate" Type="Edm.DateTime" Nullable="false"/>
<Property Name="DiscontinuedDate" Type="Edm.DateTime" Nullable="true"/>
<Property Name="Rating" Type="Edm.Int32" Nullable="false"/>
<Property Name="Price" Type="Edm.Decimal" Nullable="false"/>
<NavigationProperty Name="Category" Relationship="ODataDemo.Product_Category_Category_Products" FromRole="Product_Category" ToRole="Category_Products"/>
<NavigationProperty Name="Supplier" Relationship="ODataDemo.Product_Supplier_Supplier_Products" FromRole="Product_Supplier" ToRole="Supplier_Products"/>
</EntityType>
<EntityType Name="Category">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ID" Type="Edm.Int32" Nullable="false"/>
<Property Name="Name" Type="Edm.String" Nullable="true" m:FC_TargetPath="SyndicationTitle" m:FC_ContentKind="text" m:FC_KeepInContent="true"/>
<NavigationProperty Name="Products" Relationship="ODataDemo.Product_Category_Category_Products" FromRole="Category_Products" ToRole="Product_Category"/>
</EntityType>

 

Sample payload for Deepinsert 1:N
<Categories>
<Category>
<Name>Snacks</Name>
<ID>77</ID>
<Products> //NavigationPropertyName
<Product> //NavigationEntityName
<ID>45661211</ID>
<Rating>3</Rating>
<Supplier> //NavigationPropertyName
<Supplier> //NavigationEntityName
<ID>123451</ID>
<Concurrency>1</Concurrency>
<Address> //Complex property
<Street>Shantinagar</Street>
</Address>
</Supplier>
</Supplier>
</Product>
<Product> //NavigationEntityName
<ID>4566141</ID>
<Rating>4</Rating>
<Price>19.9</Price>
<Supplier>
<Supplier>
<ID>12344222</ID>
<Concurrency>1</Concurrency>
<Address>
<Street>Whitefield</Street>
<City>Bangalore</City>
<State>Karnataka</State>
</Address>
</Supplier>
</Supplier>
</Product>
</Products>
</Category>
</Categories>





3. Create with Reference Links


OData Adapter allows linking of two entities using <link> tag. If one has to link a new entity with an existing entity, eg. linking a new Product to an already existing Category/Supplier.

Payload Structure for Reference link
<SourceEntitySetName>
<SourceEntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
<link>
<NavigationPropertyName1>
<NavigationEntityTypeName1>
<KeyOfNavigation1>..</KeyOfNavigation1>
</NavigationEntityTypeName1>
</NavigationPropertyName1>
<NavigationPropertyName2>
<NavigationEntityTypeName2>
<KeyOfNavigation2>..</KeyOfNavigation2>
</NavigationEntityTypeName2>
</NavigationPropertyName2>
</link>
</SourceEntityTypeName>
</SourceEntitySetName>

 

Sample payload for Reference link
<Products>
<Product>
<ID>309</ID>
<ReleaseDate>2017-01-01T00:00:00</ReleaseDate>
<Rating>3</Rating>
<link>
<Supplier>
<Supplier>
<ID>1</ID>
</Supplier>
</Supplier>
<Category>
<Category>
<ID>1</ID>
</Category>
</Category>
</link>
</Product>
</Products>

 

Deepinsert with a Reference link

Below is a sample of Deepinsert of Category and Products, with link to already existing Supplier.
<Categories>
<Category>
<Name>Beverages</Name>
<ID>17</ID>
<Products>
<Product>
<ID>18</ID>
<Rating>4</Rating>
<Price>19.9</Price>
<link>
<Supplier>
<Supplier>
<ID>1</ID>
</Supplier>
</Supplier>
</link>
</Product>
</Products>
</Category>
</Categories>





4. Update (PUT)


Updates an existing Entry with a valid payload.

The Update payload must contain a single valid entity representation.

Consider an OData entry “Product” that has the following properties:
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime">1995-10-01T00:00:00</d:ReleaseDate>
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32">3</d:Rating>
<d:Price m:type="Edm.Decimal">3.5</d:Price>
</m:properties>

 

Update request, on changing Rating =4, sample payload
<Products>
<Product>
<ID>1</ID>
<Rating>4</Rating>
</Product>
</Products>

 

The above payload will result in the following properties
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime" m:null="true" />
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32">4</d:Rating>
<d:Price m:type="Edm.Decimal" m:null="true" />
</m:properties>

The properties that are not specified in payload have become null.




5. Merge (MERGE)


Update an existing entry with an entry document. It is similar to update but the properties that are not specified in payload doesn’t become null.

Consider an Odata entry “Product” that has the following properties
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime">1995-10-01T00:00:00</d:ReleaseDate>
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32">3</d:Rating>
<d:Price m:type="Edm.Decimal">3.5</d:Price>
</m:properties>

 

Merge  request, on changing Rating=4, sample payload
<Products>
<Product>
<ID>1</ID>
<Rating>4</Rating>
</Product>
</Products>

 

The above payload will result in the following properties
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime">1995-10-01T00:00:00</d:ReleaseDate>
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32">4</d:Rating>
<d:Price m:type="Edm.Decimal">3.5</d:Price>
</m:properties>

In order to insert null to an existing value, the payload must have the XML namespace schema "http://www.w3.org/2001/XMLSchema-instance" declared along with the namespace prefix.

The property with null, must have the attribute nil set to true.

Consider an OData entry “Product” that has the following properties
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime">1995-10-01T00:00:00</d:ReleaseDate>
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32">3</d:Rating>
<d:Price m:type="Edm.Decimal">3.5</d:Price>
</m:properties>

 

Merge request, on changing Rating to null, sample payload
<Products xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance>
<Product>
<ID>1</ID>
<ReleaseDate>1995-10-01T00:00:00</ReleaseDate>
<Rating xsi:nil="true"></Rating>
<Price>3.5</Price>
</Product>
</Products>


The above payload will result in the following properties
<m:properties>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ReleaseDate m:type="Edm.DateTime">1995-10-01T00:00:00</d:ReleaseDate>
<d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
<d:Rating m:type="Edm.Int32" m:null="true" />
<d:Price m:type="Edm.Decimal">3.5</d:Price>
</m:properties>

 

6. Patch (PATCH)


The payload for Patch is same as a Merge operation.

The difference between Put, Patch and Merge is as below.
























OData Operation Description HTTP operation
PUT PUT request replaces the existing Entry, so all property values in the Entry either take the values indicated in the request body, or are reset to their default value if not mentioned in the request PUT
MERGE MERGE request updates only the properties indicated in the request body, and leaves untouched anything not mentioned in its current state. POST with Method Tunneling
PATCH PATCH request updates only the properties indicated in the request body, and leaves untouched anything not mentioned in its current state. PATCH






7. Delete (DELETE)


Delete a single entity as an entry document.

For deleting a particular entity, the key identifier is required which is captured in resource path.

The payload is not required for Delete operation.






8. Batch


A detailed function of Batch is mentioned in the blog

https://blogs.sap.com/2017/05/10/batch-operation-in-odata-v2-adapter-in-sap-cloud-platform-integrati...

Batch Payload structure
<!--batchParts can contain mulitiple batchChangeSet -->
<batchParts>
<batchChangeSet>
<batchQueryPart>
<uri>Employees('1')</uri>
<!-- A query is always a GET operation. uri is mandatory-->
<headers>
<!--this is optional -->
<header>
<headerName> </headerName>
<headerValue> </headerValue>
</header>
</headers>
</batchQueryPart>
<!--a batchChangeSet may contain multiple batchChangeSetPart -->
<batchChangeSetPart>
<method>PUT/POST/DELETE</method>
<!-- The value of method must be one of PUT/POST/DELETE -->
<uri>Employees('1')</uri>
<!-- uri is mandatory for DELETE and FUNCTIONIMPORT. optional for PUT and POST method. In case of POST the uri value should be entity set name (Products in this case) or the entity set name along with its parent entity that needs to be linked (Eg: Categories(0)/Products)-->
<headers>
<!--this is optional-->
<header>
<headerName/>
<headerValue/>
</header>
<header>
<headerName/>
<headerValue/>
</header>
</headers>
<entitySetName>
<!--This structure is similar to single PUT/POST body. This is optional in DELETE -->
<entityTypeName>

</entityTypeName>
</entitySetName>
</batchChangeSetPart>
</batchChangeSet>
</batchParts>

batchParts can contain multiple batchChangeSet.

batchChangeSet can contain multiple batchChangeSetPart.

Each batchChangeSetPart must contain a single valid entity representation.

For multiple POST in Batch operation, each entity representation must be in different batchChangeSetPart along with the <method> tag. In other words, each entity has to be within a batchChangeSetPart boundary.

Sample Payload for batch with POST (DeepInsert, Reference link) PUT and DELETE.
<batchParts>
<batchChangeSet>
<batchChangeSetPart>
<method>POST</method>
<Categories>
<Category>
<ID>23</ID>
<Products>
<Product>
<ID>876</ID>
<ReleaseDate>1992-01-01T00:00:00</ReleaseDate>
<Rating>4</Rating>
<Price>2.5</Price>
</Product>
</Products>
</Category>
</Categories>
</batchChangeSetPart>
</batchChangeSet>
<batchChangeSet>
<batchChangeSetPart>
<method>POST</method>
<uri>Categories(0)/Products</uri>
<Products>
<Product>
<ID>994</ID>
<ReleaseDate>1992-01-01T19:45:22.909</ReleaseDate>
<Rating>4</Rating>
<Price>2.5</Price>
</Product>
</Products>
</batchChangeSetPart>
</batchChangeSet>
<batchChangeSet>
<batchChangeSetPart>
<method>PUT</method>
<Products>
<Product>
<ID>1</ID>
<ReleaseDate>1992-01-01T00:00:00.453</ReleaseDate>
<Rating>4</Rating>
<Price>2.5</Price>
</Product>
</Products>
</batchChangeSetPart>
</batchChangeSet>
<batchChangeSet>
<batchChangeSetPart>
<method>DELETE</method>
<uri>Categories(23)</uri>
</batchChangeSetPart>
</batchChangeSet>
</batchParts>





9. UPSERT


Payload Structure for Upsert

 




10. Function Import


Function Import can accept primitive type input parameters and can be defined to return a single primitive, single complex type, collection of primitives, collection of complex types, a single Entry, a Collection of Entries, or void.

Function Import cannot have request body.

Refer to the blog https://blogs.sap.com/2018/08/13/sap-cloud-platform-integration-odata-v2-function-import/

Function import response payload structure.

Response for Single primitive type












Schema Sample

<FunctionImportName>
<EdmTypeName>ReturnedValue</EdmTypeName>
</FunctionImportName>


<getDefaultGoalPlanTemplateId>
<Int64>1</Int64>
</getDefaultGoalPlanTemplateId>



Response for Single complex type












Schema Sample

<FunctionImportName>
<ComplexTypeName>
<Property>406</Property>
<Property>false</Property>
</ComplexTypeName>
</FunctionImportName>


<GetPermanentAddress>
<Address>
<HouseNo>406</HouseNo>
<IsRentedHouse>false</IsRentedHouse>
</Address>
</GetPermanentAddress>



Response for a collection of primitives 












Schema Sample

<FunctionImportName>
<EdmTypeName>ReturnedValue</EdmTypeName>
<EdmTypeName>ReturnedValue</EdmTypeName>
</FunctionImportName>


<getDefaultGoalPlanTemplateId>
<Int64>1</Int64>
<Int64>1</Int64>
</getDefaultGoalPlanTemplateId>



Response for a collection of complex types












Schema Sample

<FunctionImportName>
<ComplexTypeName>
<Property>406</Property>
<Property>false</Property>
</ComplexTypeName>
<ComplexTypeName>
<Property>406</Property>
<Property>false</Property>
</ComplexTypeName>
</FunctionImportName>


<GetTemporaryAddress>
<TempAddress>
<HouseNo>406</HouseNo>
<IsRentedHouse>false</IsRentedHouse>
</TempAddress>
<TempAddress>
<HouseNo>406</HouseNo>
<IsRentedHouse>false</IsRentedHouse>
</TempAddress>
</GetTemporaryAddress>



Response for a single Entry












Schema Sample

<EntitySetName>
<EntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</EntityTypeName>
</EntitySetName>


<Products>
<Product>
<Price>2.5</Price>
<ID>0</ID>
</Product>
</Products>



Response for a collection of Entities












Schema Sample

<EntitySetName>
<EntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</EntityTypeName>
<EntityTypeName>
<PropertyName>PropertyValue</PropertyName>
<PropertyName>PropertyValue</PropertyName>
</EntityTypeName>
</EntitySetName>


<Products>
<Product>
<Price>2.5</Price>
<ID>0</ID>
</Product>
<Product>
<Price>2.5</Price>
<ID>0</ID>
</Product>
</Products>



10.1 Function Import in $batch


Function Import can be configured with batch processing. Function import with GET HttpMethod is supported in T1913 delivery.

Request Schema
<batchParts>
<batchChangeSet>
<batchChangeSetPart>
<method>Http Method of the Function Import</method>
<uri>FunctionImportName?FuncImportParameter=value</uri>
<!-- uri is mandatory for Function Import. It has to be the functionImport name with all the parameters.-->
<headers>
<!--this is optional-->
<header>
<headerName/>
<headerValue/>
</header>
</headers>
</batchChangeSetPart>
</batchChangeSet>
</batchParts>

 

Response Schema
<batchPartsResponse>
<batchChangeSetReponse>
<batchChangeSetPartReponse>
<statusCode/>
<statusInfo/>
<contentId/>
<headers>
<header>
<headerName> </headerName>
<headerValue> </headerValue>
</header>
</headers>
<body>
<!--This structure is similar to single function Import Response-->
</body>
</batchChangeSetPartReponse>
</batchChangeSetReponse>
</batchPartsResponse>








 

6 Comments