Consumed OData Service

Last modified: February 13, 2024

1 Introduction

When an external entity or action is used in an app module through the Integration pane, a consumed OData service document is added specifying the details of the consumed service. This is the API to the publishing app and the data associated with the entity.

2 Consumed OData Service screen

The Consumed OData Service document contains the following information:

Connection Tab
  • Service name and icon for the source application of the originating app

  • Version number of the consumed service

  • View in Catalog link to the Service Details where you can see the full details that are registered

  • Update/Switch – You can update the consumed service contract to another version that has been detected in the Catalog for the same app and service. The button will show the following, depending on what has been returned for the consumed contract:

    • Update – This button is displayed so you can update the contract that is currently consumed and shown in the Consumed OData Service document. You will be presented with the contract that is currently at the service endpoint. It is good practice that only minor, non-breaking changes are deployed to the same endpoint.
    • Switch – This button is shown if other registered instances of the same service with the same name, from the same app are available in the Catalog, but are deployed to different endpoints (for example, to another environment or because of changes that would break existing apps consuming the previous version)

2.1 Service URL

The Service URL displays the URL of the service endpoint:

  • Click Select to choose another constant for the service

  • Click Show to open the Constant dialog box displaying the service URL or endpoint:

2.2 Timeout

Timeout is the response time for fetching data from the service endpoint. If the endpoint has not responded after the number of seconds in Timeout (s), an exception will occur. If this happens during a microflow activity, the microflow will roll back or go into your custom error handling.

Default value: 300 seconds

2.3 Proxy Configuration

Proxy configuration allows you to configure a proxy for the request:

  • Use app settings – use settings which are defined at the app level (default)
  • Override – override the app-level settings for this action by specifying the host, port, user name, and password settings for the proxy
  • No proxy – do not use a proxy for this service, even if there is a proxy configured at the app level

2.4 Authentication

The Use HTTP authentication checkbox specifies if basic authentication should be used. If selected, specify the following details:

  • User name – defines the user name that will be used for authentication
  • Password – defines the password that will be used for authentication

Input these as a string with single quotes.

In addition to basic authentication, you can also use custom authentication. For more information, see the HTTP Headers section below.

2.5 HTTP Headers

You can specify additional HTTP request headers to be passed to the endpoint in this list by clicking Add, Edit, or Delete for custom HTTP headers for authentication. Each custom header is a pair with a key and a value.

Using Headers from a Microflow, you can specify a microflow for creating a key and value pair (or pairs) for dynamic values. The microflow must return a list of System.HttpHeader objects.

2.5.1 Authenticating with Mendix SSO

Publishers can set up custom authentication using Mendix SSO module. For more information, see the Mendix SSO section of Published OData Services.

Consumers of an OData service that is set up with Mendix SSO authentication can use the CreateAccessTokenAuthorizationHeaderList.

To learn more about how to publish an OData service with authentication (Mendix SSO, or other methods), see the Authentication Methods section of Published OData Services.

To learn more about using external entities with security enabled (in production environments), see the Authentication section of External Entities.

2.6 Error Handling Microflow

When a call to the OData service fails, users see a generic error message. Create an error-handling microflow to change this message.

When the service responds with an unsuccessful status code (not in the 2xx range), or does not return a response at all, this microflow decides which message to show to the user.

The microflow should have an argument of type System.HttpResponse. If the OData service returns a response, the argument has a value. Otherwise, it is empty.

The microflow must return a String containing the error message. If it returns empty, the original generic message is used.

Note for developers of java actions: the message returned by the error handling microflow can be caught as a UserException.

2.7 Metadata

When you create a consumed OData service, the metadata editor allows you to open an OData contract from a file or URL. If you have already consumed a contract, you can click Update to update the existing contract with a new version from a file or URL.

To open the Metadata Editor, click Update. In the editor, you can specify a URL or file for the metadata:

Metadata Editor

The following settings are available:

  • Import from – select URL or File for the location of the metadata
    • URL – specify the URL for the metadata

    • File – click Browse to select a metadata file

      You can use the URL of a file that contains the metadata, such as https://services.odata.org/V4/Northwind/Northwind.svc/$metadata. You can also click Share Data Source in the details of a data source in the Catalog and paste that value.

When downloading the metadata from a URL, the server may request a user name and password (basic authentication). If this happens, a dialog box will prompt you to enter your user name and password. If the metadata file refers to other metadata files on the same server within the same realm, the user name and password are reused.

When you import the metadata, you can add external entities and actions from the consumed OData service in the Integration pane.

2.8 Properties

Click the Properties tab for the consumed OData service which displays the properties that were defined for the OData service document and the following additional properties:

  • Entities – the URL of the metadata defining the entities and associated datasets
  • Documentation – an additional description about this service for the current app
  • Service name – the name of the published OData service that is consumed
  • Service version – the version of the service that is consumed
  • Service ID – the unique identifier of the service in the Catalog
  • Application ID – the unique identifier of the application that the service was published from in the Catalog
  • Metadata – the contents of the metadata file defining the service
  • OData version – the OData version (can be v3 or v4)

2.8.1 Using QuerySegment

When set to No, the application retrieves data using a GET HTTP method and places data query arguments in the URL’s query string.

When set to Yes, a POST HTTP method is used, /$query is appended to the resource path of the URL and the query string is provided as the request body. This enables limiting the length of the URL and avoiding potential problems with the systems involved. This feature is not available for OData v3 or if the consumed service explicitly indicates that it is not supported. For details, see Passing Query Options in the Request Body in the OData specification.

3 Updating or Switching a Consumed OData Service

3.1 Consuming from Service Endpoints

When you add an external entity to your app, you are consuming the entity from a specific version of a service (the service endpoint), deployed to a given environment. The metadata file or contract for the service is located at this endpoint.

The same service deployed to a different environment will be to a different service endpoint and registered as a different asset in the Catalog. In the following example, there are three endpoints for the Sales 1.0.0 service, which is deployed to the production environment and the Acceptance and Test environments:

2 endpoints

When you drag the Customer entity from CustomerApi version 1.0.0 deployed to the Acceptance environment into your app, Studio Pro retrieves the information it requires from the contract that is at that endpoint.

3.2 Semantic Numbering for Service Versions

It is important the publishers of the services adopt a strict revision process for any changes they make to their published OData services that are consumed by other users.

It is recommended to use a strict versioning system, such as semantic numbering, when issuing updates to services. The service version should clearly indicate the level and severity of the changes that have been made when a service is updated and deployed according to the following guidelines.

3.2.1 Minor Service Updates

Minor service updates are, for example, additional fields added to the service or new operations that would not break any apps that consume the previous versions.

If semantic numbering is used, then a minor/non-breaking change to a service can be indicated by an increase in the decimal part of the version number. For example, 1.0.11, 1.0.12, 1.1, 1.2.

Minor service updates can be deployed to the same service endpoints, which ensures that all consuming apps consume the latest version of the service.

3.2.2 Major Service Updates

Major service updates are, for example, when entities or attributes are removed, or input parameters are required. Such updates would be incompatible for the consuming apps and result in the consuming app “breaking.”

When a major change has been made to a published service, Mendix recommends the service is deployed to a different endpoint with the new service version number that clearly indicates there has been a major change. With semantic numbering, this would be an incremental increase of a whole number.

In this case, the new service should be registered in the Catalog as a different service and show up as a separate asset. In the following example, there are four registered occurrences of the OrderManagementService:

4 endpoints

There is a major service update indicated by the change in the version number from 1.0.0 to 2.0.0. Both major versions have been deployed to Acceptance, which results in separately registered assets in the Catalog at different endpoints.

3.3 Update or Switch

When a change in the contract at a consumed endpoint is detected (possibly due to a minor change), or if the same named service is deployed with a major version number but to a different endpoint, the following options are available in the Consumed OData Service screen.

3.3.1. Update

The Update option is available when Studio Pro detects that the contract at the Catalog endpoint is different than the one currently consumed in the app. If Update is selected, the new contract will be loaded in the app.

See the Limitations section of Consumed OData Services to read about known update limitations.

3.3.1.1 Integration Pane

In the Integration pane, search results, and in the Used in your App section, an update arrow indicates if there is a different contract at the Catalog endpoint.

update service app-pane
  • The service version that is currently consumed is shown (in this example 1.0.0).
  • Blue Update - click to open the Update Service box and update the contract. Studio Pro will retrieve the new contract at the Catalog endpoint, which will be loaded in the app.
  • The list of entities in this new version in the Catalog are shown, including the locally consumed entities that are marked with a green check mark. These entities are, however, greyed out to indicate that they cannot be dragged into the domain model because the contract for the previous version is currently being consumed. The only option is to click Update to retrieve the updated OData Service.
3.3.1.2 Update Service Dialog Box

When you click Update on the Consumed OData Service document or the update icon in the Mendix Connect and App sections, the Update dialog box is displayed.

The consumed OData service that is currently consumed in the app (1.0.0) is shown on the left. Click Update to retrieve the new contract from Mendix Connect (2.0.0).

3.3.2. Switch

When an OData service is published to a different endpoint or environment, it will be registered as a different asset in the Catalog.

In the example in the Consuming from Service Endpoints section above, if you are consuming the service from the Acceptance environment, the Consumed OData service screen will display the Switch button to enable you to consume the same service from the Production.

3.3.3 Switching Consumed Services

A published OData service that is deployed to multiple environments or is published with major service updates (and therefore deployed to a different endpoint) is shown as separate items in the search results of the Integration pane.

In the following example, the consumed Orders version 1.0.0 deployed to Test environment is consumed in the app. However, the same service is deployed to the Acceptance environment:

major change environment

To consume the service deployed to the Acceptance environment, follow these steps:

  1. Click Update > Switch on the Consumed OData Service document:

    major change environment
  2. On the Switch dialog box, from the drop-down list, select the service you want to consume from (note that an endpoint is also detected that is deployed to Production) and click Switch:

    major change environment
  3. The consumed service is be consumed from the new selected environment. The information on the Consumed OData Service document displays the changed service details and the Integration pane will display that you are consuming from the selected environment:

4 Read More