OData Connector

This adapter enables communication with systems that provide ReST services according to the OData standard, e.g. SAP S4/Hana, Microsoft Sharepoint, Microsoft Dynamics Navision and others.

Properties

Operation

Defines the operation executed by the adapter

Possible values:

ReadMetadata: Retrieve the data model and operations exposed by a specific service.
ReadCollections: Retrieve all collections available from the service.
ReadEntitySet: Retrieve a particular collection from the service.
ReadSingleEntity: Retrieve a single entity from the service specified by its collection and ID.
ReadNavigationEntity: Retrieve the related collection to the entity.
ReadAssociation: Retrieve the related association to the entity.
ReadSingleton: Retrieve the specific singleton.
ReadMediaEntity: Retrieve the media entity.
CreateEntity: Create new entities in the system, which are specified by Collection and ID in an input XML document.
UpdateEntity: Update specific entities existing in the system, specified by Collection and ID in an input XML document.
DeleteEntity: Delete specific entities existing in the system, specified by Collection and ID in an input XML document.
CreateSingleton: Create a new singleton in the system, specified by Collection and ID in an input XML document.
UpdateSingleton: Update a specific singleton existing in the system, specified by Collection and ID in an input XML document.
DeleteSingleton: Delete a specific singleton existing in the system, specified by Collection and ID in an input XML document.
CreateMediaEntity: Create new media entities in the system, specified by Collection and ID within the parameters entitySet and entityId.
UpdateMediaEntity: Update specific media entities existing in the system, specified by Collection and ID within the parameters entitySet and entityId.
DeleteMediaEntity: Delete specific media entities existing in the system, specified by Collection and ID within the parameters entitySet and entityId.
Functions: Request a specific operation (Function, Action) exposed by the service, retrieving correspondent output values.

Parameters

`Adapter`	Main adapter class (do not change!) Possible values: de.softproject.x4.adapter.odataquery.ODataQueryAdapter: Main class (default)
`serviceUrl`	OData service URL, e.g. `https://services.odata.org/V4/TripPinServiceRW`
`entitySet`	Entity collection to interact with.
`entityId`	Entity ID to interact with.
`navigationProperty`	Retrieve related collection to the entity
`association`	Retrieve related association to the entity
`singletonId`	Singleton ID
`contentTypeMetadata`	ContenType of the service metadata Possible values: `Full`: Output complete metadata `Minimnal`: Output only basic metadata `None`: Do not output any metadata

Status values

`1`	The operation was executed successfully and an output is generated
`-1`	An error occurred during the operation's execution an no output is generated.

Input

Depending on the selected operation, the adapter expects the following input structure:

The operations ReadaMetadata, ReadSingleEntity, ReadNavigationEntity, ReadSet and ReadSingleton do not require any input document. However the parameters entitySet and entityId are required.
The operation ReadAssociation does not require any input document. However the parameters entitySet, entityId and association are required.
Operation ReadEntitySet:
The following system query options can be used with the operation ReadEntitySet:
- $count: Ignores any $top, $skip, or $expand query options, and returns the total count of results across all pages including only those results matching any specified $filter and $search.
- $skip: If $top and $skip are used together, $skip must be applied before $top, regardless of the order in which they appear in the request.
- $top: Allows the user of an OData service to specify the maximum number of entries that should be returned, starting from the beginning.
- $orderby: When requesting a list of entities from a service, it is up to the service implementation to decide in which order they are presented.
- $filter: When requesting a list of entities from a service, the default behaviour is to return all entities on the list. The consumer of an OData service might want to be able to receive a subset by specifying certain criteria which each of the returned entities have to fulfill.
- $select: When requesting an entity collection from the backend, the OData service returns a list of entities and each entity contains a list of properties.
  - Specify one property name only: $select=Name
  - Specify a comma-separated list of properties: $select=Name,Description
  - Specify a star to include all properties: $select=*
- $expand: Indicates the related entities and stream values that must be specified inline.
- $search: Restricts the result to include only those items matching the specified search expression.
- $format: Specifies the media type of the response.

ReadEntitySet

XML

<Request>
	<QueryOptions entitySet="Products">
		<Parameter name="format" value="application/xml"></Parameter>
		<Parameter name="search" value="Ergo"></Parameter>
		<Parameter name="top" value="10"></Parameter>
		<Parameter name="skip" value="5"></Parameter>
		<Parameter name="count"></Parameter>
		<Parameter name="filter" value="ID le 10"></Parameter>
		<Parameter name="count" value="true"></Parameter>
		<Parameter name="expand">
			<Items>Category</Items>
		</Parameter>
		<Parameter name="select">
			<Items>ID</Items>
			<Items>Description</Items>
		</Parameter>	
	</QueryOptions>
</Request>

Operations CreateEntity, UpdateEntity and DeleteEntity:

CreateEntity, UpdateEntity and DeleteEntity Request

XML

<Request>
       <Entity qualifiedName="Microsoft.OData.SampleService.Models.TripPin.Person" entitySet="People">
             <Property name="UserName" value="carlosreyestest" type="String" isId="true"/>
             <Property name="FirstName" value="Carlos" type="String"/>
             <Property name="LastName" value="Carlos" type="String"/>
             <Collection name="AddressInfo">
                  <Property type="Microsoft.OData.SampleService.Models.TripPin.Location">
                     <Property name="Address" value="Calle Falsa 123" type="String"/>
                     <Property name="City" type="Microsoft.OData.SampleService.Models.TripPin.City">
                           <Property name="CountryRegion" value="Espana" type="String"/>
                           <Property name="Name" value="Madrid" type="String"/>
                           <Property name="Region" value="Madrid" type="String"/>
                     </Property>
                  </Property>
             </Collection>
       </Entity>
</Request>

Operations CreateSingleton, UpdateSingleton and DeleteSingleton:

CreateSingleton, UpdateSingleton and DeleteSingleton Request

XML

<Request>
       <Singleton qualifiedName="Microsoft.OData.SampleService.Models.TripPin.Person" entitySet="People">
             <Property name="UserName" value="carlosreyestest" type="String" isId="true"/>
             <Property name="FirstName" value="Carlos" type="String"/>
             <Property name="LastName" value="Carlos" type="String"/>
             <Collection name="AddressInfo">
                  <Property type="Microsoft.OData.SampleService.Models.TripPin.Location">
                     <Property name="Address" value="Calle Falsa 123" type="String"/>
                     <Property name="City" type="Microsoft.OData.SampleService.Models.TripPin.City">
                           <Property name="CountryRegion" value="Espana" type="String"/>
                           <Property name="Name" value="Madrid" type="String"/>
                           <Property name="Region" value="Madrid" type="String"/>
                     </Property>
                  </Property>
             </Collection>
       </Singleton>
</Request>

For the operations CreateMediaEntity, UpdateMediaEntity and DeleteMediaEntity the parameters entitySet and entityId are required as well as the media input within the adapter.

Operation ExecuteFunction:

ExecuteFunction Request

XML

<?xml version="1.0" encoding="UTF-8"?>
<Request>
       <Function name="CountCategories">
             <Parameter name="Amount" value="2"></Parameter>
       </Function>
</Request>

Supported types

Adapter Input Type	Type	Meaning
`Binary`	`Edm.Binary`	Binary data
`Boolean`	`Edm.Boolean`	Binary-valued logic
`Byte`	`Edm.Byte`	Unsigned 8-bit integer
`Date`	`Edm.Date`	Date without a time-zone offset
`DateTimeOffset`	`Edm.DateTimeOffset`	Date and time with a time-zone offset, no leap seconds
`Decimal`	`Edm.Decimal`	Numeric values with decimal representation
`Double`	`Edm.Double`	IEEE 754 binary64 floating-point number (15-17 decimal digits)
`Duration`	`Edm.Duration`	Signed duration in days, hours, minutes, and (sub)seconds
`Guid`	`Edm.Guid`	16-byte (128-bit) unique identifier
`Int16`	`Edm.Int16`	Signed 16-bit integer
`Int32`	`Edm.Int32`	Signed 32-bit integer
`Int64`	`Edm.Int64`	Signed 64-bit integer
`SByte`	`Edm.SByte`	Signed 8-bit integer
`Single`	`Edm.Single`	IEEE 754 binary32 floating-point number (6-9 decimal digits)
`String`	`Edm.String`	Sequence of UTF-8 characters

Output

Depending on the selected operation, the adapter outputs the following structures:

Operation ReadMetadata:

ReadMetadata Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx Version="4.0"
	xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
	<edmx:DataServices>
		<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm"
			Namespace="OData.Demo">
			<EntityType Name="Product">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Int32"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<Property Name="Description" Type="Edm.String"></Property>
				<NavigationProperty Name="Category"
					Type="OData.Demo.Category" Partner="Products"></NavigationProperty>
			</EntityType>
			<EntityType Name="Category">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Int32"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<NavigationProperty Name="Products"
					Type="Collection(OData.Demo.Product)" Partner="Category"></NavigationProperty>
			</EntityType>
			<EntityType Name="Advertisement" HasStream="true">
				<Key>
					<PropertyRef Name="ID" />
				</Key>
				<Property Name="ID" Type="Edm.Guid"></Property>
				<Property Name="Name" Type="Edm.String"></Property>
				<Property Name="AirDate" Type="Edm.DateTimeOffset"></Property>
			</EntityType>
			<Action Name="Reset" IsBound="false">
				<Parameter Name="Amount" Type="Edm.Int32"></Parameter>
			</Action>
			<Function Name="CountCategories">
				<Parameter Name="Amount" Type="Edm.Int32" Nullable="false"></Parameter>
				<ReturnType Type="Collection(OData.Demo.Category)" />
			</Function>
			<EntityContainer Name="Container">
				<EntitySet Name="Products" EntityType="OData.Demo.Product">
					<NavigationPropertyBinding
						Path="Category" Target="Categories" />
				</EntitySet>
				<EntitySet Name="Categories"
					EntityType="OData.Demo.Category">
					<NavigationPropertyBinding
						Path="Products" Target="Products" />
				</EntitySet>
				<EntitySet Name="Advertisements"
					EntityType="OData.Demo.Advertisement"></EntitySet>
				<ActionImport Name="Reset" Action="OData.Demo.Reset"></ActionImport>
				<FunctionImport Name="CountCategories"
					Function="OData.Demo.CountCategories"
					EntitySet="OData.Demo.Categories" IncludeInServiceDocument="true"></FunctionImport>
			</EntityContainer>
		</Schema>
	</edmx:DataServices>
</edmx:Edmx>

Operations ReadSingleEntity and ReadSingleton:

ReadSingleEntity Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
	<Value type="String" name="@odata.context">$metadata#Products/$entity</Value>
	<Value type="Number" name="ID">1</Value>
	<Value type="String" name="Name">Notebook Professional 17</Value>
	<Value type="String" name="Description">Notebook Professional, 2.8GHz - 15 XGA
		- 8GB DDR3 RAM - 500GB</Value>
</Object>

Operation ReadEntitySet:

ReadEntitySet Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
   <Value type="String" name="@odata.context">$metadata#Products</Value>
   <Array name="value">
      <Object>
         <Value type="Number" name="ID">0</Value>
         <Value type="String" name="Name">Notebook Basic 15</Value>
         <Value type="String" name="Description">Notebook Basic, 1.7GHz - 15 XGA - 1024MB DDR2 SDRAM - 40GB</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">1</Value>
         <Value type="String" name="Name">Notebook Professional 17</Value>
         <Value type="String" name="Description">Notebook Professional, 2.8GHz - 15 XGA - 8GB DDR3 RAM - 500GB</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">2</Value>
         <Value type="String" name="Name">1UMTS PDA</Value>
         <Value type="String" name="Description">Ultrafast 3G UMTS/HSDPA Pocket PC, supports GSM network</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">3</Value>
         <Value type="String" name="Name">Comfort Easy</Value>
         <Value type="String" name="Description">32 GB Digital Assitant with high-resolution color screen</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">4</Value>
         <Value type="String" name="Name">Ergo Screen</Value>
         <Value type="String" name="Description">19 Optimum Resolution 1024 x 768 @ 85Hz, resolution 1280 x 960</Value>
      </Object>
      <Object>
         <Value type="Number" name="ID">5</Value>
         <Value type="String" name="Name">Flat Basic</Value>
         <Value type="String" name="Description">Optimum Hi-Resolution max. 1600 x 1200 @ 85Hz, Dot Pitch: 0.24mm</Value>
      </Object>
   </Array>
</Object>

Operation ReadCollections:

ReadCollections Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
	<Value type="String" name="@odata.context">$metadata</Value>
	<Array name="value">
		<Object>
			<Value type="String" name="name">Products</Value>
			<Value type="String" name="url">Products</Value>
		</Object>
		<Object>
			<Value type="String" name="name">Categories</Value>
			<Value type="String" name="url">Categories</Value>
		</Object>
		<Object>
			<Value type="String" name="name">Advertisements</Value>
			<Value type="String" name="url">Advertisements</Value>
		</Object>
		<Object>
			<Value type="String" name="name">CountCategories</Value>
			<Value type="String" name="url">CountCategories</Value>
			<Value type="String" name="kind">FunctionImport</Value>
		</Object>
	</Array>
</Object>

Operations CreateEntity, UpdateEntity and DeleteEntity:

CreateEntity, UpdateEntity and DeleteEntity Response

XML

<Response>
	<OKEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="1" name="ID"/>
		<Property type="String" value="Car" name="Name"/>
		<Property type="String" value="Good car" name="Description"/>
	</OKEntities>
	<FailEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="2" name="ID"/>
		<Property type="String" value="Cookie" name="Name"/>
		<Property type="String" value="Great cookie" name="Description"/>
	</FailEntities>
</Response>

Operations CreateSingleton, UpdateSingleton and DeleteSingleton:

CreateSingleton, UpdateSingleton and DeleteSingleton Response

XML

<Response>
	<OKEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="1" name="ID"/>
		<Property type="String" value="Car" name="Name"/>
		<Property type="String" value="Good car" name="Description"/>
	</OKEntities>
	<FailEntities entitySet="Products" qualifiedName="OData.Demo.Product">
		<Property isId="true" type="int32" value="2" name="ID"/>
		<Property type="String" value="Cookie" name="Name"/>
		<Property type="String" value="Great cookie" name="Description"/>
	</FailEntities>
</Response>

Operation ExecuteFunction:

ExecuteFunction Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<Object>
       <Value type="String" name="@odata.context">$metadata#Collection(OData.Demo.Category)
       </Value>
       <Array name="value">
             <Object>
                    <Value type="Number" name="ID">0</Value>
                    <Value type="String" name="Name">Notebooks</Value>
             </Object>
             <Object>
                    <Value type="Number" name="ID">1</Value>
                    <Value type="String" name="Name">Organizers</Value>
             </Object>
             <Object>
                    <Value type="Number" name="ID">2</Value>
                    <Value type="String" name="Name">Monitors</Value>
             </Object>
       </Array>
</Object>