Skip to Content
Technical Articles
Author's profile photo Saranya Baskaran

Payload structure in OData V4 adapter – SAP Cloud Integration

SAP Cloud Integration has OData V4 adapter with which various OData operations can be done on an OData V4 endpoint.

This blog covers the payload structure for various Data modification operations like

  1. Create
  2. Deep Insert
  3. Update

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

Primitive Types Description Literal form Sample in payload
Edm.Boolean Binary-valued logic true true
Edm.Date Date without a time-zone offset date’2014-01-03′ 2014-01-03
Edm.DateTimeOffset Date and time with a time-zone offset, no leap seconds datetimeoffset’2014-01-03T10:00:00Z’ 2014-01-03T10:00:00Z
Edm.Decimal Numeric values with fixed precision and scale 2.345M 2.345M
Edm.Double IEEE 754 binary64 floating-point number (15-17 decimal digits) 2.029d 2.029d
Edm.Duration Signed duration in days, hours, minutes, and (sub)seconds duration’PT0S’ 20D5H2S
Edm.Guid 16-byte (128-bit) unique identifier guid’dddddddd-dddd-dddd-dddd-dddddddddddd’ 12345678-aaaa-bbbb-cccc-ddddeeeeffff
Edm.Int16 Signed 16-bit integer 16 16
Edm.Int32 Signed 32-bit integer 32 32
Edm.Int64 Signed 64-bit integer 64L 64L
Edm.Single IEEE 754 binary32 floating-point number (6-9 decimal digits) 2.0f 2.0f
Edm.String Sequence of UTF-8 characters ‘russellwhyte’ russellwhyte
Edm.TimeOfDay Clock time 00:00-23:59:59.999999999999 timeofday’12:30:00.00′ 12:30:00.00

1. Create

To create an entity in a collection, body MUST contain a single valid entity representation.

Properties with Edm type having Collection should have each of its value enclosed within <element> tags.

Request Schema

<EntitySetName>
	<EntityTypeName>
		<PropertyName>PropertyValue</PropertyName>
		<PropertyName>PropertyValue</PropertyName>
		<PropertyName>                            //Property with type Collection of Primitive
			<element>PropertyValue</element>
		</PropertyName>
		<PropertyName>                            //Property with type Collection of Complex   
			<element>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>PropertyValue</PropertyName>
			</element>
			<element>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>PropertyValue</PropertyName>
			</element>
		</PropertyName>
	</EntityTypeName>
</EntitySetName>

 

Sample payload for Microsoft hosted V4 service https://services.odata.org/TripPinRESTierService/(S(samplePayload))/

<People>
	<Person>
		<UserName>russellwhyte</UserName>
		<FirstName>Russell</FirstName>
		<LastName>Whyte</LastName>
		<MiddleName />
		<Gender>Male</Gender>
		<Age />
		<Emails>
			<element>Russell@example.com</element>
			<element>Russell@contoso.com</element>
		</Emails>
		<FavoriteFeature>Feature1</FavoriteFeature>
		<Features>
			<element>Feature1</element>
			<element>Feature2</element>
		</Features>
		<AddressInfo>
			<element>
				<Address>187 Suffolk Ln.</Address>
				<City>
					<Name>Boise</Name>
					<CountryRegion>United States</CountryRegion>
					<Region>ID</Region>
				</City>
			</element>
		</AddressInfo>
		<HomeAddress />		
	</Person>
</People>

 

2. Deep Insert

A request to create an entity that includes related entities, represented using the appropriate inline representation, is referred to as a “deep insert”.

Request Schema for Deep insert

<EntitySetName>
	<EntityTypeName>
		<PropertyName>PropertyValue</PropertyName>
		<PropertyName>PropertyValue</PropertyName>
		<PropertyName>
			<element>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>PropertyValue</PropertyName>
			</element>
		</PropertyName>
		<NavigationPropertyName>        //Navigation Property with type Single Entity 
			<EntityTypeName>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>
					<element>PropertyValue</element>
				</PropertyName>				
			</EntityTypeName>
		</NavigationPropertyName>
		<NavigationPropertyName>        //Navigation Property with type collection of Entity 
			<EntityTypeName>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>
					<element>PropertyValue</element>
				</PropertyName>				
			</EntityTypeName>
			<EntityTypeName>
				<PropertyName>PropertyValue</PropertyName>
				<PropertyName>
					<element>PropertyValue</element>
				</PropertyName>				
			</EntityTypeName>
		</NavigationPropertyName>
	</EntityTypeName>
</EntitySetName>

From the below edmx, The Entity “Person” has navigation to BestFriend with target type as a single Person

Entity “Person” also has navigation to Trips which is a collection of Trip.

<EntityType Name="Person">
	<Key>
		<PropertyRef Name="UserName"/>
	</Key>
	<Property Name="UserName" Type="Edm.String" Nullable="false"/>
	<Property Name="FirstName" Type="Edm.String" Nullable="false"/>
	<Property Name="LastName" Type="Edm.String"/>
	<Property Name="MiddleName" Type="Edm.String"/>
	<Property Name="Gender" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.PersonGender" Nullable="false"/>
	<Property Name="Age" Type="Edm.Int64"/>
	<Property Name="Emails" Type="Collection(Edm.String)"/>
	<Property Name="AddressInfo" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location)"/>
	<Property Name="HomeAddress" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location"/>
	<Property Name="FavoriteFeature" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature" Nullable="false"/>
	<Property Name="Features" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature)" Nullable="false"/>
	<NavigationProperty Name="Friends" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person)"/>
	<NavigationProperty Name="BestFriend" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person"/>
	<NavigationProperty Name="Trips" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Trip)"/>
</EntityType>

2.1 Sample Payload for deep insert with the target type single entity

<People>
	<Person>
		<UserName>russellwhyte</UserName>
		<FirstName>Russell</FirstName>
		<LastName>Whyte</LastName>
		<Gender>Male</Gender>
		<AddressInfo>
			<element>
				<Address>187SuffolkLn.</Address>
				<City>
					<Name>Boise</Name>
					<CountryRegion>UnitedStates</CountryRegion>
					<Region>ID</Region>
				</City>
			</element>
		</AddressInfo>
		<BestFriend>
			<Person>
				<UserName>scottketchum</UserName>
				<FirstName>Scott</FirstName>
				<LastName>Ketchum</LastName>
				<Gender>Male</Gender>
				<Emails>
					<element>Scott@example.com</element>
				</Emails>
				<FavoriteFeature>Feature1</FavoriteFeature>
				<AddressInfo>
					<element>
						<Address>2817MiltonDr.</Address>
						<City>
							<Name>Albuquerque</Name>
							<CountryRegion>UnitedStates</CountryRegion>
							<Region>NM</Region>
						</City>
					</element>
				</AddressInfo>			
			</Person>
		</BestFriend>
	</Person>
</People>

2.2 Sample Payload for deep insert with the target type collection of Entity

<People>
	<Person>
		<UserName>russellwhyte</UserName>
		<FirstName>Russell</FirstName>
		<LastName>Whyte</LastName>
		<Gender>Male</Gender>
		<FavoriteFeature>Feature1</FavoriteFeature>
		<Features>
			<element>Feature1</element>
			<element>Feature2</element>
		</Features>		
		<BestFriend>
			<Person>
				<UserName>scottketchum</UserName>
				<FirstName>Scott</FirstName>
				<LastName>Ketchum</LastName>
				<Gender>Male</Gender>
				<Emails>
					<element>Scott@example.com</element>
				</Emails>
				<FavoriteFeature>Feature1</FavoriteFeature>
				<AddressInfo>
					<element>
						<Address>2817MiltonDr.</Address>
						<City>
							<Name>Albuquerque</Name>
							<CountryRegion>UnitedStates</CountryRegion>
							<Region>NM</Region>
						</City>
					</element>
				</AddressInfo>
				<HomeAddress/>
				<Trips>
					<Trip>
						<TripId>3</TripId>
						<ShareId>9d9b2fa0-efbf-490e-a5e3-bac8f7d47354</ShareId>
						<Name>TripinUS</Name>
						<Budget>5000</Budget>
						<Description>TripfromSanFranciscotoNewYorkCity</Description>
						<Tags>
							<element>business</element>
							<element>NewYorkmeeting</element>
						</Tags>
						<StartsAt>2014-01-01T00:00:00Z</StartsAt>
						<EndsAt>2014-01-04T00:00:00Z</EndsAt>
					</Trip>
					<Trip>
						<TripId>4</TripId>
						<ShareId>f94e9116-8bdd-4dac-ab61-08438d0d9a71</ShareId>
						<Name>TripinBeijing</Name>
						<Budget>11000</Budget>
						<Description>Trip from Shanghai to Beijing</Description>
						<Tags>
							<element>Travel</element>
							<element>Beijing</element>
						</Tags>
						<StartsAt>2014-02-01T00:00:00Z</StartsAt>
						<EndsAt>2014-02-04T00:00:00Z</EndsAt>
					</Trip>
				</Trips>
			</Person>
		</BestFriend>
	</Person>
</People>

2. Update (PATCH)

Updates an existing Single Entry with a valid payload

<People>
	<Person>
		<UserName>lewisblack</UserName>
		<FirstName>Lewis</FirstName>
		<Gender>Male</Gender>
		<LastName>Black</LastName>
		<element>lewisblack@example.com</element>
		<element>lewisblack@noone.com</element>
		<AddressInfo>
			<element>
				<Address>187 Suffolk Ln.</Address>				
			</element>
			<element>
				<Address>188 Suffolk Ln.</Address>
				<City>
					<CountryRegion>United States</CountryRegion>
					<Name>Boise</Name>
					<Region>ID</Region>
				</City>
			</element>
		</AddressInfo>
		<FavoriteFeature>Feature1</FavoriteFeature>
	</Person>
</People>

Assigned tags

      4 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Dennis Sentler
      Dennis Sentler

      Hello and thanks for providing the guide!

       

      I've one question regarding the navigation properties.
      If I would like to reuse a already existing entry for an entity. Can I somehow link them together? Like you explained in the OData V2 guide: Payload structures in OData V2 adapter for SAP Cloud Integration | SAP Blogs Part: Ref Links.

       

      Thanks in advance

      Cheers

      Dennis

      Author's profile photo Saranya Baskaran
      Saranya Baskaran
      Blog Post Author

      Hi Dennis,

      OData V4 adapter is relatively new compared to OData V2 adapter. There are a lot of features not supported yet in V4 adapter. Update Related Entities When Updating an Entity is not yet supported.

      Regards
      Saranya

      Author's profile photo Dennis Sentler
      Dennis Sentler

      Saranya Baskaran unfortunately this information in this blog seem to be wrong!

      I have tried to use this tutorial regarding updating navigation properties (section Deep Insert). But it did not work out for me. So I have contacted the technical support from SAP.

      The support contacted the development team for this exact adapter (OData V4 Receiver Adapter). I've this response:

      Information%20regarding%20the%20odata%20v4%20adapter

      Information regarding the odata v4 adapter

      Saranya Baskaran or do you have more information of how to use the odata adapter for updating the navigation properties?

       

      Author's profile photo Saranya Baskaran
      Saranya Baskaran
      Blog Post Author

      Hi Dennia,

      This blog had the sample for Update (Updates an existing Single Entry with a valid payload).

      Update corresponds to PATCH operation.
      Deep Insert corresponds to POST operation. Deep Insert is where you create a new entry and create a new navigation entry. Deep insert is not deep update. Hope this clarifies the confusion.

      Regards
      Saranya