. . .

OData Connector

Introduction

The OData connector allows you to read and write data from servers that provides an OData RESTful service v2. For example it gives you the possibility to access data of a SAP system if your SAP Gateway provides an OData service.

When you trigger the cr it creates an ApiOmat module with classes and properties according to the provided OData metadata entities and properties.

After crawling has finished you're able to access the data from a frontend in the known ApiOmat way.

Key Capabilities

Capability

Description

Converting OData entities to ApiOmat classes

With the crawling you're able to create ApiOmat classes and properties from metadata which are provided by the odata service

Reading data

Reading data from odata collections

Querying data

Sending Odata filter queries to retrieving filtered data from service (see OData filter query section below)

Reading references

Getting data of navigation properties

Saving/Update data

Add a new entry to a collection or update existing one

Module Setup & Configuration

Parameter-Name

Default Value

Explanation

Thread-pool-size

0

Number of threads used to create the Metamodels and Attributes. Should be set to 0 to trigger an automatic computation of values. Change only if you encounter any problems with the computed values

enable logging

false

If set to true detailed logging will be enabled

Crawling

Crawling is the essential part of this connector. It converts the OData metadata to a new ApiOmat module with classes and properties. If you start crawling a new module will be created prefixed with given module name.

The crawling process can be started via dashboard or REST call. Find below the explanation of config parameters:

Parameter-Name

Required

Example

Explanation

Base URL

images/wiki.apiomat.com/s/en_GB/7202/2b917bf474320363b63231a29396d24a46356543/_/images/icons/emoticons/check.png

http://services.odata.org/V2/OData/OData.svc

URL to the OData RESTful v2 service

apiOmat module name

images/wiki.apiomat.com/s/en_GB/7202/2b917bf474320363b63231a29396d24a46356543/_/images/icons/emoticons/check.png

CrawlProducts

Prefix for new (or updated) module. Module name will consisting of <prefix>+<app backend name>

apiOmat Customer name

images/wiki.apiomat.com/s/en_GB/7202/2b917bf474320363b63231a29396d24a46356543/_/images/icons/emoticons/check.png

mustermann

Name of the customer which owns the app backend

addtional http headers send to odata interface

SSL_CLIENT_CERT|SSL_CLIENT_VERIFY

list of header names seperated by | whose values given from client will be forwarded to OData service

TRUE to overwrite previous crawling

TRUE

If set to TRUE then existing module with same name will be overwritten

App name

images/wiki.apiomat.com/s/en_GB/7202/2b917bf474320363b63231a29396d24a46356543/_/images/icons/emoticons/check.png

ODataSampleApp

Name of the app backend where new module will be created for

Dashboard

After adding OData Connector from marketplace to your app backend you must navigate to My Modules > Native Modules and go to the section labeled ODataConnector. There you have to fill-in the config parameters and click on button "Triggers a new crawling process"

images/download/attachments/63116891/odataExampleDashboard.PNG

After refreshing your module list (go to Module Market > Refresh) the crawled module should be visible within your app backend's navigation bar. To create and read the data of the crawled module use the data editor in your Dashboard.

images/download/attachments/63116891/Odata_crawledModule_data_editor_3_0.png

The guide Data gives some detail on how to create and read data object instances.

REST Call

Crawling OData entities may also be triggered via REST by calling the following endpoint (see API docs for more information):

curl -X GET --header 'Accept: text/plain' --header 'X-apiomat-system: LIVE' --header 'If-None-Match: false' --header 'X-apiomat-apikey: 887157215189025405' -u demoUser:password
'http://localhost:8080/yambas/rest/modules/odataconnector/DemoBackend/spec/crawler?url=http%3A%2F%2Fservices.odata.org%2FV2%2FOData%2FOData.svc&moduleName=RestCrawlProducts&customerName=demoUser&reCrawl=true'

A successfully crawled module can then be querried by the module REST endpoint:

curl -X GET --header 'Accept: application/json' --header 'X-apiomat-system: LIVE' --header 'If-None-Match: false' --header 'X-apiomat-apikey: 887157215189025405' -u demoUser:password
'http://localhost:8080/yambas/rest/modules/RestcrawlproductsDemoBackend'

For more details about creating and reading data object instances just visit the section Using the REST interface.

OData Service Authentication

Sometimes you need to authenticate against an OData Service. The OData user and password that is needed to crawl OData entities have to be applied to the base url. Those information are placed in front of the domain name of the OData base url, e.g.:

http://odataTommy:myPass@services.odata.org/V2/OData/OData.svc

The OData Connector module internally extracts username and password and sets them as connection credentials to the OData crawling request.

These credentials must be from a technical user (instead of a session user). They get saved in the ApiOmat database in an object of a meta data class in the app's scope instead of as module configuration, because module configuration is valid across apps, but the credentials should only be visible for the app for which the service was crawled.

OData Filter Query

One of OData's feature is to filter your responses by query. Normally you would do this by appending $filter=<values> (see Odata filter queries).
The ODataConnector module contains an own REST parameter to define a specific query. This query parameter will be delegated to the OData Service as odata filter.

Example:

The ApiOmat GET REST call to the end point ...

doGetAll Request
<Apiomat_Yambas_BASE_URL>/apps/<appName>/models/<crawledModuleName>/Cars?q=Price+lt+200000

... will be internally transferred to the OData service call ...

OData Request
<ODataService_BASE_URL>/Cars/?$filter=Price+lt+200000


Dashboard Example:

Via Dashboard you can define your OData filter query within the provided query input field:

images/download/attachments/63116891/dashboard_query.PNG

OData Composite Primary Keys

OData supports objects with multiple primary keys. To query those objects via OData REST call you need to append all keys to the REST end point, e.g. https://host/service/Orders(1)/Items(OrderID=1,ItemNo=2) .

During the OData service crawling those object will be converted to ApiOmat objects with combined foreignId. The combined foreignId looks like the following:

foreignId
<firstPrimaryKey>__<secondPrimaryKey>
e.g.:
1__2
1__2__3

The order of combined foreignId elements is important. Currently it has to be the same order like the defined ODataService primary key compound.

Limitations

At the moment:

  • data cannot be updated (doPut)

  • data cannot be deleted (doDelete)

  • referenced data cannot be removed (doDeleteRef)

  • referenced data cannot be added (doPostRef)

Furthermore a new data instance can only be created if all OData properties of the entity are present.