Skip to main content

OData Execution

info

Available for Flex (SSIS) and Gems (Pre-built)

Overview​

To execute package and get resulting data via the COZYROC OData Service the packages must to be developed according to the guidelines in the OData Package Development section. OData aware clients can access the service if they comply to the requirements below.

Requirements​

  • Client is compatible with OData V4 protocol.
  • Client can utilize header authorization via header token.
  • User has a valid authorization token obtained from the COZYROC Cloud web application.

Getting and using an authorization token​

To get and use an authorization token:

  1. Login to the COZYROC Cloud web application.
  2. Under Profile expand the Personal Access Token section.
  3. Click on Generate, provide token name and click on Submit.
  4. Copy the generated token.
  5. In your OData client set Authorization header with the value of the copied token.
info

We support two types of authorization

  • Personal Access Token
  • Basic Authorization

Example: Setting authorization header with Personal Access Token in Postman.

img

Example: Setting Basic authorization in Postman

img

Where Username is your email in COZYROC Cloud web application and for Password you should use the generated Personal Access Token.

Getting Service Document and Metadata​

To get the OData Service Document and Metadata for the available resources you should issue the corresponding request to the following URLs:

Service Documents​

There are three service documents, depending on your subscription plan you will have access to one or more of them:

  • https://odata.cozyroc.cloud/packages - Lists all package resources offered by the service. This document is available to Flex Managed subscriptions.
  • https://odata.cozyroc.cloud/gems - Lists all installed gem resources offered by the service. This document is available to Gems and Flex Managed subscriptions.
  • https://odata.cozyroc.cloud/workspace - This document is available to Partners and lists the gem resources in your workspace so they can be tested.

Example: Getting Service Document with Postman.

img

Metadata​

The Service metadata exposes self-describing document for resources (as entity sets), their fields and their corresponding OData types. It can be accessed under

  • https://odata.cozyroc.cloud/packages/$metadata for packages.
  • https://odata.cozyroc.cloud/gems/$metadata for gems.
  • https://odata.cozyroc.cloud/workspace/$metadata for Partner's workspace gems.

Example: Getting Metadata with Postman.

img

Refreshable metadata​

Packages and gems that implement refreshable resources will require the Refresh Resources action before you can inspect or execute them.

img

Accessing resources through the OData service​

Upon issuing a GET request for specific Entity Set the corresponding package or gem hosted in the COZYROC Cloud will be executed and the results will be returned to the caller formatted according to the OData standard. The execute URL is available under the Resources section of the corresponding Package / Gem details page.

img

Example: Executing a package with Postman.

img

Execution with parameters​

Parameters declared during development can be set in the OData service call - the values set for them will be passed to the package at the execution start.

To allow a parameter to be passed in the query string of your OData request, you need to enable Resource param option explicitly for each parameter. Go to Parameters panel and click on the edit button, check the Resource param, click Apply and then Save.

img

Upon Save your OData Execute URL will be updated automatically in the Details panel. You can copy it.

img

note

If you pass a parameter as a query string parameter but the parameter is not marked as a Resource param from the UI. Then the package execution will most probably fail.

Example: Setting package parameter with Postman.

img

Using OData $select parameter​

OData defines the $select parameter to restrict the fields displayed in the result set. Please, note that when using $select to limit the fields displayed this is done in the OData service and not in the package itself. Therefore it is still required that all desired columns are added to the package data flow output and it is better to restrict the columns in the package output than through the $select parameter.

img

Cursor pagination with $skiptoken​

To allow efficient access to large data sets the COZYROC OData Service implements cursor pagination. Desired page size can be set through pageSize parameter in the request. If no pageSize value is provided the service will default to 200 records per page. If there are more pages available the OData service will return @odata.nextLink with a link containing the cursor to the next page.

Example: Setting page size and using cursor pagination with Postman.

img

note

There is a limit on how long the service will keep the next page available. Therefore timeout errors can occur if client waits too long before requesting the next page.