Skip to Content

You can perform various operations in the OData V2 Adapter for SAP Cloud Platform Integration.

This blog covers the payload structure for various Data modification operations like Create, Merge, Update, upsert, Batch and Delete.

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.

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

Deep insert is a functionality which allows the application to create single entities deeply.

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:

  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>

 

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>

 

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>

 

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 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>

 

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:

Update request, on changing Rating =4, sample payload

The above payload will result in the following properties

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

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

Merge  request, on changing Rating =4, sample payload

The above payload will result in the following 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

Merge request, on changing Rating to null, sample payload

The above payload will result in the following properties

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.

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-integration/

Batch Payload structure

<!--batchParts can contain mulitiple batchChangeSet -->
<batchParts>
	<batchChangeSet>
		<!--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. 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>
			</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 mulitiple batchChangeSet.

batchChangeSet can contain multiple batchChangeSetPart.

Each batchChangeSetPart must contain 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 boundry.

Sample Payload for batch with POST (DeepInsert, Referance 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>

UPSERT

OData Adapter consumes upsert feature which is exposed by the SFSF service.

Upsert payload can have deep-insert and reference link.

Upsert Payload structure

<SourceEntitySetName>
	<SourceEntityTypeName>
		<propertyN>..</propertyN>
		<NavigationPropertyName1>	
			<NavigationEntityTypeName1>
				<keyOfNavigation1>..</keyOfNavigation1>
			</NavigationEntityTypeName1>
		</NavigationPropertyName1>
		<NavigationPropertyName2>
			<NavigationEntityTypeName2>
				<keyOfNavigation2>..</keyOfNavigation2>
			</NavigationEntityTypeName2>
		</NavigationPropertyName2>
	</SourceEntityTypeName>
	<SourceEntityTypeName>
		<propertyN>..</propertyN>
		<link>
			<NavigationPropertyName1>
				<NavigationEntityTypeName1>
					<keyOfNavigation1>..</keyOfNavigation1>
				</NavigationEntityTypeName1>
			</NavigationPropertyName1>
			<NavigationPropertyName2>
				<NavigationEntityTypeName2>
					<keyOfNavigation2>..</keyOfNavigation2>
				</NavigationEntityTypeName2>
			</NavigationPropertyName2>
		</link>
	</SourceEntityTypeName>
</SourceEntitySetName>

Sample payload for upsert

The sample below has upsert with deepinsert and reference link.

<User>
	<User>
		<userId>user1</userId>
		<status>active</status>
		<username>user1</username>
		<manager>
			<User>
				<userId>user22</userId>
				<status>active</status>
				<username>user22</username>
			</User>
		</manager>
	</User>
	<User>
		<userId>user33</userId>
		<status>active</status>
		<cellPhone>9876543210</cellPhone>
		<firstName>Tony</firstName>
		<link>
			<hr>
				<User>
					<userId>user1</userId>
				</User>
			</hr>
		</link>
	</User>
</User>

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply