Chapter 20. Connecting to OData

Open Data Protocol (OData) is a standard for building and consuming REST APIs. An OData service provides services to clients, such as Fuse Online, through OData-compliant HTTP requests. A Fuse Online integration can obtain entities from an OData service, and can update, create, or delete entities managed by an OData service. To do this, create an OData connection, and add it to an integration.

It is assumed that you are familiar with the OData specification.

Details for connecting to an OData service are in the following topics:

20.1. Creating a connection to an OData service

In an integration, to obtain, update, create, or delete entities that are managed by an OData service, you must first create a connection to that OData service.

Prerequisites

  • You must know the base URL for the OData service that you want to connect to.
  • If that service uses authentication then you must have the required credentials, and, if required, an SSL certificate. However, most OData services are public and do not require authentication.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. Click Create Connection to display connectors.
  3. Click the OData connector.
  4. To configure the connection:

    1. In the Service Root URL field, enter the base URL for the OData service that you want to access.
    2. In the User Name field, if the service uses basic authentication, then enter your user name.
    3. In the Password field, if the service uses basic authentication, then enter your password.
    4. In the Server Certificate field, if the service requires it, paste the content of an SSL certificate.

      Typically, a public OData service does not require a certificate in addition to the certificates provided by the browser. However, for an internal OData service, you might have created your own SSL certificate and self-signed it. Since this certificate is not trusted by a certificate authority, connections to your OData service would fail. To enable connections, paste the self-signed certificate here.

      One way to get the certificate is to load the service in a browser. The steps after that depend on which browser you are using, but it will be something like the following: click the Not secure padlock symbol next to the address bar, then click View Certificate, export the displayed certificate to a file, copy the certificate, and paste it into this field.

  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameter(s) and try again.
  6. When validation is successful, click Next.
  7. In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter OData North.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. Click Save to see that the connection you created is now available. If you entered the example name, you would see that OData North appears as a connection that you can choose to add to an integration.

Next step

Add your OData connection to an integration.

20.2. Triggering an integration when polling returns data from an OData service

To trigger execution of an integration upon obtaining data from an OData service, add an OData connection to a simple integration as its start connection. When the integration is running, the OData connection polls the service at intervals that you specify. When the connection finds data that satisfies the connection configuration, the connection passes the data to the next step in the integration.

Prerequisite

You created an OData connection.

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the OData connection that you want to use to start the integration.
  4. On the Choose an action page, select the Read action.
  5. Configure the Read action:

    1. In the Resource Collection field, select the name of the OData resource that you want to query. Fuse Online fetches data from the OData service to provide a list of available resource collections.
    2. In the Entity Key Predicate field, to obtain a particular entity, identify the entity that you want by specifying its key predicate. For example, specify something like UserName='Bob' or Categories(1). To obtain multiple entities, leave this field blank.
    3. In the Query Options field, enter a query that you want to apply to the resource. Use OData syntax. For example, $filter=startswith(name, 'N') returns a message for each entity in the resource that has a name field that starts with N.

      You can specify both Entity Key Predicate and Query Options. If you do, the OData service obtains the specified entity and applies the query to that entity. For example, suppose that you set Entity Key Predicate to UserName='russellwhyte'/Emails and you set Query Options to $filter=contains($it,'example'). The connection creates a request that looks something like this:

      https://services.odata.org/TripPinRESTierService/People(UserName='russellwhyte')/Emails?$filter=contains($it, 'example')

      The service returns all email addresses for Russell Whyte that contain the domain example.

    4. Select the Filter Old Results checkbox to obtain a particular message only once.
    5. Select the Split Results checkbox if you want the connection to return individual messages rather than a collection of messages.

      Fuse Online also provides discrete split and aggregate steps, which you can add to a flow. If you want to process individual messages in one or more steps and then aggregate the messages into a collection, do not select the Split Results checkbox. Instead, leave the checkbox empty and then add a split step to the flow after this connection. A split step is required if you want an aggregate step in the flow.

    6. In the Interval Before Polling Starts field, accept the default of 1 second, or enter the length of time that you want to elapse before the connection starts to poll the OData service.
    7. In the Delay field, accept the default of 30 seconds, or enter the interval at which you want the connection to poll the OData service.
    8. In the Backoff Idle Threshold field, accept the default of 1 or enter an integer that indicates the number of consecutive polls that can return no data. After this number of polls, the connection increases the interval between subsequent polls. The connection determines the new length of the polling interval by multiplying the Delay value by the Backoff Multiplier value.

      For example, suppose that the polling interval (the Delay value) is the default of 30 seconds, Backoff Idle Threshold is set to 5, and Backoff Multiplier is set to 12. After 5 consecutive polls that return no data, the connection waits 360 seconds (30 x 12) before polling again. The connection continues to poll every 360 seconds until a poll returns data. After a poll returns data, the connection resumes polling every 30 seconds.

    9. In the Backoff Multiplier field, accept the default of 1 or enter an integer that indicates the multiplier for increasing the polling interval if the value set for the Backoff Idle Threshold is reached.

      If you accept the default of 1 for the Backoff Multiplier, then the connection continues to poll at the specified interval no matter how many consecutive polls return no results.

      The values that you specify for Backoff Idle Threshold and Backoff Multiplier are useful for reducing CPU overhead since the connection can automatically poll less often during quiet periods.

  6. Click Next.

Result

The integration now has a start connection and Fuse Online is prompting you to choose the finish connection.

During execution, what the connection returns depends on what you specified in the Entity Key Predicate and Query Options fields. The OData connection can return:

  • A collection of entities or a collection of entity properties

    For example, this might be all Person entities in the resource, or perhaps all Age properties for all Person entities. The connection returns the collection in one message. Fuse Online executes each subsequent step in the flow once for the collection. However, when you configure the Read action, if you select Split Results, then the connection returns each entity or each property in its own message. Fuse Online executes each subsequent step in the flow once for each message.

  • An entity or an entity property

    For example, this might be the Person entity whose UserName property is Bob, or perhaps the Age property for the Person entity whose UserName is Bob. The connection returns the entity or the entity property in a message that it passes to the next step in the flow.

Next steps

Add the integration’s finish connection and any other connections that you want to include in the integration. When the integration contains all the connections that are needed, if the OData connection returns a collection, consider whether you need to add a split step after the OData connection. An integration usually needs to map the data returned by the OData connection to fields that a subsequent connection in the flow can use. Sometimes you can map a collection, but more often you need to split the collection in order to map to the target fields.

After the OData connection, add a data mapper step to the flow. Exactly where in the flow depends on what you want the flow to do. For example, after the OData connection, you might add a basic filter step and then add a data mapper step.

20.3. Updating, creating, and deleting data that is managed by an OData service

In an integration, you can update a resource that is managed by an OData service in the middle of a flow or to finish a simple integration. To do this, add an OData connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • You created an OData connection.
  • You are creating or editing an integration and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add an OData connection. Skip this step if you are adding a simple integration’s finish connection.
  2. Click the OData connection that you want to use. Note that when an OData connection updates or deletes an entity, the connection does not return anything. When the OData connection creates an entity, the connection returns the new entity.
  3. On the Choose an action page, select the action that you want the connection to perform:

    • Create adds an entity to an OData resource.
    • Delete removes an entity from an OData resource.
    • Update changes an entity that is in an OData resource.
  4. Configure the action by selecting the OData resource that you want to update.

    It is important for you to have an understanding of how the OData resource that you are updating is set up. The backing data source for an OData service determines the rules for updates and resolving conflicts. For example, suppose an OData connection tries to create a new entity but an entity with that predicate key already exists. The OData service might overwrite the existing entity, or it might update some fields in the existing entity, or it might ignore the operation. It is up to you to know how the OData service behaves in this situation.

  5. Click Next.

Result

The connection appears in the integration visualization where you added it.

Next steps

Add a data mapper step before the OData connection. You must map source fields that provide the data that is required to create a new entity, to update an entity, or to delete an entity. See Mapping integration data to fields for the next connection.