Use an OData Service in Analytics Designer or Optimized Story Experience

In SAP Analytics Cloud, analytics designer or Optimized Story Experience, you can define OData services based on an existing on-premise SAP S/4HANA live connection in your system that was created via CORS (​​cross-origin resource sharing) connectivity. Additionally, you can also define OData services based on SAP BW systems, SAP HANA systems, and SAP Business Planning and Consolidation (BPC) systems that were also created via CORS.

You can create an OData service, define the endpoint URL and use script APIs to let viewers trigger transactional actions at the backend, such as filling out an order form or others.

In analytics designer amd Optimized Story Experience, OData actions can be called from and executed in the backend system via scripting. Furthermore, it's also possible to read and use the data of entity sets exposed via OData services via APIs.

What You Should Know

  • OData actions are operations exposed by an OData service, which may have side effects when invoked.

  • OData action imports, also called unbound actions, are not associated with any OData entity set or entity. They generally expose simple parameters. All parameters are set via POST body.

  • OData bound actions are actions that may be invoked on a specific entity. They always contain a first parameter that is set via URL to resolve the binding to the entity within the relevant entity set, and all other parameters are set via POST body.

    In general, actions can be bound on every type, but in analytics designer and Optimized Story Experience, only binding on single entities is supported.

  • For OData you should configure the direct connection CORS at the backend. To follow the instructions on the connection configuration, refer to Live Data Connections to SAP S/4HANA. In connection configuration, the CORS connection is referred to as direct connection.

    Note

    Please find the following additional configuration information:

    • The service path you configure should correspond to the end-point URL of the OData service.

    • In addition to the service path listed in the documentation, you need to add another service path /sap/opu/odata4/

    • The connection should also support if-match as allowed header.

There're following restrictions:

  • Only parameters of simple types are supported. Actions with mandatory parameters of unsupported types are not available. For actions with optional parameters of unsupported types, the action itself is supported, but those parameters are not.

  • In case of bound actions, actions bound to an entity collection are not supported. Only actions bound to a single entity are supported. It's only possible to set this binding parameter by specifying the key of the entity on which the action should be carried out.

  • Only the JSON format is supported.

  • Only S/4HANA on-prem is supported.

  • Only direct connection, CORS, is supported.

  • The following types are not supported:

    • Edm.Stream

    • Edm.Untyped

    • All Edm.Geography types

    • All types defined in different name space

Add an OData Service

To execute an OData action, you need to first add an OData service with the corresponding actions to your analytic application or optimized story.

Prerequisites

The end-point URL of the OData service is available. You need to enter it manually when creating the service.

Procedure

  1. In the Scripting section of Outline, (for analytic applications) choose right next to OData Services, or (for optimized stories) choose Start of the navigation path Next navigation step OData ServicesEnd of the navigation path.

    The OData services technical object is created, with the default name ODataService_1 displayed in Outline. A side panel opens on the right.

  2. In the side panel, do the following:
    1. (Optional) Change the default name of the new service to a meaningful name.
    2. Under Connections, select the system from the list of available SAP S/4HANA systems whose connections were already created in SAP Analytics Cloud.
    3. Manually enter a valid end-point URL of the OData Service, in the format /some/end_point/url/.

      You need to know the URL because browse catalog isn't available.

  3. Select (Refresh) next to Metadata to review the metadata of the new OData service.
  4. Select Done to close the panel.

Results

Now you can use the OData action. For more examples, see Scripting Example 1: Use OData Actions in Analytics Designer or Optimized Story Experience and Scripting Example 2: Use OData Actions in Analytics Designer or Optimized Story Experience.

Use APIs to Read Data from OData Services

With OData services you can not only can access OData actions, but also read and use the data of entity sets exposed via OData services.

This lets you use the data of the entity sets for any purpose except data visualization in a table or a chart. For example, you can read and display one member in a text widget. To access entity sets exposed via OData Services, you can use two APIs in your script:

  • getEntity: Retrieves a single OData entity from an entity set by specifying the key to the entity. This is similar to selecting a single row from a SQL table via SELECT * FROM T1 WHERE ID = <id>.

  • getEntitiesFromEntitySet: Retrieves all entities from an OData entity set. This is similar to SELECT TOP <N> * FROM T1. With this API you can use the OData system query options filter, orderby, select, count, top and skip.
    Note

    The number of entities is limited to 1000 if no system query options have been used. If system query options are set, there's no limit to the number of retrieved entities, unless you set a value for the system query option top.

  • getEntitiesCountFromEntitySet: Retrieves the number of entities from an OData entity set. This API works like the getEntitiesFromEntitySet API and you can also use the OData system query options filter, orderby, select, count, top and skip.

Example
The parameters filter, orderby and select have string values, which will be 1:1 used in the OData request. This allows you to use all features supported by the query options. The parameters skip and top have integer values, which will be used in the OData request. The second parameter in both API methods is passed as object, in which the system query options can be combined in an arbitrary way.
Sample Code
// returns a list of entities, filtered by the given system query option(s)
ODataService_1.getEntitiesFromEntitySet("Departments", {filter: "contains(Sector,'Consulting')", orderby: "Sector asc" });
// returns a list of entities, not filtered
ODataService_1.getEntitiesFromEntitySet("Equipments");
// returns the number of entities in the entity set "TEAMS"
ODataService_2.getEntitiesCountFromEntitySet("TEAMS");
// returns the number of entities in the entity set "EMPLOYEES", filtered by the given system query option(s)
ODataService_2.getEntitiesCountFromEntitySet("EMPLOYEES", {skip: 5, top: 10});
Note
There're following restrictions in reading data from OData services:

  • Chaining from one entity set to another isn't supported.

  • expand, analogous to joining, isn't supported.

  • Entity sets with parameters aren't supported.

  • Entity sets with mandatory filters aren't supported.