OData provider
The OData provider is a general purpose provider designed to let you import and export data to and from DynamicWeb through the OData protocol using standard REST methods.
Used as source provider
The OData provider can be used as source provider to import data from a predefined endpoint. The OData provider is built to work with standard OData RESTful APIs.
It is possible to use both single - and multi entity endpoints for OData activities. The OData provider auto-detects if a single entity is specified or not, by checking if the final "/" in the URL is followed by an entity set name. If not, the provider will automatically look up the full metadata page. Examples of single - and multi entity endpoints:
- Single entity: "https://api.businesscentral.dynamics.com/v2.0/myTenantID/MyBC/ODataV4/Company('myCompany')/DynamicwebVendorCard"
- Multi entity: "https://myCompany.crm4.dynamics.com/api/data/v9.0/"
The endpoint provider as source can be paired with any destination provider - appropriate choices would often be the Dynamicweb provider, User provider or Ecom provider.
Source provider settings
OData import modes
When using the OData provider as a source, you have three import modes to choose from.
| Mode | Description |
|---|---|
| Delta replication | By locating the time of the last successful run this mode will import new records only. No records are deleted from DynamicWeb when this mode is used. It is possible to set a custom Delta modifier field to which the timestamp of the last successful run is compared. The Delta modifier field takes a single column name or a list of comma separated column names. If none of the provided column names exist in the source table, the delta modifier defaults to the following list of column names: Last_Date_Modified, Order_Date, LastDateTimeModified, lastModifiedDateTime, modifiedon. Note: Delta replication converts all Datetime attributes to UTC time for accurate timezone comparison. |
| First page | Imports the first page of records only. The maximum amount of records on a page is specified in the maximum page size setting. |
| Full replication | This mode imports all records and deletes nothing in DynamicWeb. Selected by default. When handling large quantities of data, it is advised to only run an activity once in this mode. |
Filtering OData requests
When using the OData provider as source, there are two ways of filtering the response from the remote system:
The first method is to apply query parameters to the predefined endpoint used in the activity.
The second method is to apply conditionals to the table mappings of an activity. When a conditional is applied to an OData import, the type and value are translated to an OData key/value pair and applied to the request made by the provider. If a query parameter with the same key is already applied to the endpoint, it will be overridden by the table mapping conditional. Use the activity log to inspect the actual request sent by the provider.
Other settings
Maximum pages size: This field can be used in conjunction with the First page mode to limit the number of records in an import. It can also be used to set the page size when running an activity in intervals, as described below. If Maximum page size is set to zero, the default page size of the remote system is applied.
Request timeout: Takes a value of minutes that sets a timer on how long the activity is allowed to run before it is automatically aborted.
Run last request: Every time the OData provider makes a request to an OData endpoint, the response is stored as a file in files/integration/response. When the Run last request box is checked, the OData provider does not query the endpoint, but instead the activity uses the latest version of the response file as source. This can be useful in case you need to restore data after a failed run. When Do not store last response in log file is checked, the response log file is not overwritten by the next response. This setting is only available when running in full replication mode.
Run request in intervals: Use this field to specify how many pages (of the size set in the maximum page field) should be queried by a single run of the activity. Subsequent runs of the same activity will continue from the next page until the full source has been read. This is useful when dealing with large amounts of data in the remote system and want to make an import less error prone by storing smaller chunks of the source data separately. An intended use of this functionality may also be simply to avoid overloading the remote system. It is advised not to run requests in intervals in the Delta replication mode.
Used as destination provider
The OData provider can be used as a destination provider to export data to a remote system using the OData protocol.
To do so, you must first define an endpoint in Endpoint collections that exposes the relevant entities. Just like when using the OData provider as source, both single - and multi entity endpoints can be used.
The OData provider uses custom key columns to detect if the record already exists in the remote system database and if it should POST a new record or PATCH an existing one. Make sure to configure a set of key columns that always uniquely identifies a record in the remote system. If the response from the endpoint contains more than one record that matches the provided key(s), the activity will fail.
Response mappings
In some cases, when exporting data via the OData protocol, the remote system may generate a response from which you might wish to stamp fields onto the source objects. For instance, a scenario could be that:
- An activity exports users from DynamicWeb to an external ERP via the OData protocol
- The ERP assigns an auto ID to each user
- The ERP sends a response to DynamicWeb including these auto IDs
- You want to enrich the user records in the DynamicWeb with the external IDs
In order to stamp information like this back onto the source, the response mapping functionality of integration activities can be utilized.
To do so, click Response mappings in the action menu of the Mappings screen.
This will take you to a mapping screen similar to the one where you added mappings to the remote system in the first place.
By default, the screen will mirror the table mappings defined in the activity to which you can add the column mappings you wish to establish. Notice that the source columns available are equivalent to the destination columns in the original data mappings screen.
The response mappings can include mappings between columns that are not defined/active in the activity mappings screen, but can only include table mappings already defined in the activity.
