// This module is included in the following assemblies:
// as_connecting-to-odata.adoc

[id='adding-odata-connections-read_{context}']
= 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

. In the {prodname} panel on the left, click *Integrations*.
. Click *Create Integration*.
. On the *Choose a connection* page, click the OData connection that
you want to use to start the integration. 
. On the *Choose an action* page, select the *Read* action.
. Configure the *Read* action: 

.. In the *Resource Collection* field, select the name of the OData resource   
that you want to query. {prodname} fetches data from the 
OData service to provide a list of available resource collections. 
.. 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. 

.. 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`. 

.. Select the *Filter Old Results* checkbox to obtain a particular 
message only once. 
.. Select the *Split Results* checkbox if you want the 
connection to return individual messages 
rather than a collection of messages. 
+
{prodname} 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. 

.. 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. 
.. 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. 

.. 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.

.. 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. 

. Click *Next*. 

.Result
The integration now has a start connection and {prodname} 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. {prodname} 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. {prodname} 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.  
