diff --git a/content/en/docs/refguide/modeling/integration/odata-services/consumed-odata-services/consumed-odata-service.md b/content/en/docs/refguide/modeling/integration/odata-services/consumed-odata-services/consumed-odata-service.md index 8d1739b27ec..f8e25aa7a98 100644 --- a/content/en/docs/refguide/modeling/integration/odata-services/consumed-odata-services/consumed-odata-service.md +++ b/content/en/docs/refguide/modeling/integration/odata-services/consumed-odata-services/consumed-odata-service.md @@ -3,8 +3,8 @@ title: "Consumed OData Service" url: /refguide/consumed-odata-service/ weight: 10 aliases: - - /refguide/consumed-odata-service-properties -# SB: The images on this page are created using the Lato-LandscapeDemoApp (https://sprintr.home.mendix.com/link/project/1b515494-d818-4358-8c91-6c3d54e9cae5) + - /refguide/consumed-odata-service-properties +# The images on this page were created using vitest screenshots and the Lato-LandscapeDemoApp (https://sprintr.home.mendix.com/link/project/1b515494-d818-4358-8c91-6c3d54e9cae5) --- ## Introduction @@ -17,109 +17,123 @@ You can create a consumed OData service and specify its metadata in a file or a The **Consumed OData Service** document contains the following information: -{{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png" alt="Connection Tab" width="850" class="no-border" >}} +{{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png" alt="Connection Tab" width="650" class="no-border" >}} -* 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](/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) +- 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](/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) - {{% alert color="info" %}} Studio Pro will always show the **Update** option for the **Consumed OData Service** where you can check if an update is available. In the Catalog search and **App** pane, when a different contract is detected at the service endpoint, it will be indicated with an update arrow for the service. For more information on updating and switching services, see the [Updating or Switching a Consumed OData service](#updating) section of this document. {{% /alert %}} + {{% alert color="info" %}} Studio Pro will always show the **Update** option for the **Consumed OData Service** where you can check if an update is available. In the Catalog search and **App** pane, when a different contract is detected at the service endpoint, it will be indicated with an update arrow for the service. For more information on updating and switching services, see the [Updating or Switching a Consumed OData service](#updating) section of this document. {{% /alert %}} - {{% alert color="info" %}}In the [Integration pane](/refguide/integration-pane/), consumed services display an **Update** icon (a blue arrow) if there is an update available.{{% /alert %}} + {{% alert color="info" %}}In the [Integration pane](/refguide/integration-pane/), consumed services display an **Update** icon (a blue arrow) if there is an update available.{{% /alert %}} ### Configuration -There are three ways to specify the service URL, headers, and proxy settings: **Constants only**, **Configuration microflow**, and **Headers microflow**. +You can use either constants or a microflow to set the service URL and proxy settings. -* **Constants only** – specify the service URL, proxy settings, and headers using constants -* **Configuration microflow** – specify the service URL, proxy settings, and headers using a microflow that returns a **System.ConsumedODataConfiguration** -* **Headers microflow** – specify headers using a microflow that returns a list of **System.HttpHeader** and specify the service URL and proxy settings using constants +- Use constants when the service URL and proxy settings are always the same. +- Use a connection microflow when you need more control. See section [connection and headers microflow](#connection-and-headers-microflow) below for more details. -### Configuration/headers microflow +### Service URL {#service-url} -Choose a microflow that returns one of the following options: +The **Service URL** displays a constant that specifies the URL of the service endpoint: -* A **System.ConsumedODataConfiguration** object with associated **System.HttpHeader** objects (when using **Configuration microflow**) -* A list of **System.HttpHeader** objects (when using **Headers microflow**) +- Click **Select** to choose another [constant](/refguide/constants/) for the service. +- Click **Show** to open the **Constant** dialog box displaying the service URL or endpoint. -This microflow may take a parameter of type **System.HttpResponse**. The microflow is called every time a request is made. Initially, the HTTP response parameter will be empty. If the service responds with `401 Unauthorized`, the microflow is called with that HTTP response and another call is made with the new HTTP headers. +### Connection microflow + +The **Connection microflow** displays the microflow that the app uses to retrieve the service URL, proxy settings and headers. See section [connection and headers microflow](#connection-and-headers-microflow) for details about how to create such a microflow. + +- Click **Select** to choose another microflow. +- Click **Show** to navigate to the microflow. + +### Proxy Configuration + +{{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/proxy.png" alt="Connection Tab" width="650" class="no-border" >}} + +**Proxy configuration** allows you to configure a proxy for the request: + +- **Follow app settings** – use settings which are defined at the app level (default). +- **Override app settings** – override the app-level settings for this action by specifying constants for the host, port, user name, and password for the proxy. +- **No proxy** – do not use a proxy for this service, even if there is a proxy configured at the app level. {{% alert color="info" %}} -Custom authentication can be done with the microflow where the authentication value is retrieved (such as SSO). For more information on access and authentication, see [Using Custom HTTP Header Validation for Published Entities](/refguide/security-shared-datasets/#http-header-validation) in *Security and Shared Datasets*. +In most cases, this setting can be ignored and the default **Follow app settings** can be used. {{% /alert %}} -#### Authenticating with Mendix SSO {#authenticate-mendix-sso} +### Authentication {#authentication} -{{% alert color="warning" %}} -The Mendix SSO module is deprecated as of May 1, 2026. For new implementations, it is recommended to configure custom authentication using [OIDC SSO](/appstore/modules/oidc/), [SAML](/appstore/modules/saml/), or [LDAP](/appstore/modules/ldap/) modules. -{{% /alert %}} +{{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/authentication.png" alt="Connection Tab" width="650" class="no-border" >}} -Publishers can set up [custom authentication](/refguide/published-odata-services/#authentication-microflow) using [Mendix SSO](/appstore/modules/mendix-sso/) module. For more information, see the [Mendix SSO](/refguide/published-odata-services/#authentication-mendix-sso) section of *Published OData Services*. +The choice for **Basic authentication** specifies if basic authentication should be used. If selected, specify the following details: -Consumers of an OData service that is set up with Mendix SSO authentication can use the **CreateAccessTokenAuthorizationHeaderList**. +- **User name** – an expression for the user name that will be used for authentication. +- **Password** – an expression the password that will be used for authentication. + +In addition to basic authentication, you can also use custom authentication. For more information, see the [HTTP Headers](#http-headers) section below. -To learn more about how to publish an OData service with authentication (Mendix SSO, or other methods), see the [Authentication Methods](/refguide/published-odata-services/#authentication-methods) section of *Published OData Services*. +### HTTP Headers {#http-headers} -To learn more about using external entities with security enabled (in production environments), see the [Authentication](/refguide/external-entities/#authentication) section of *External Entities*. +{{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/http-headers.png" alt="Connection Tab" width="650" class="no-border" >}} -### Service URL {#service-url} +Choose **Add headers** to add specify additional HTTP request headers to be passed to the endpoint. + +The list allows you to **Add**, **Edit**, or **Delete** custom HTTP headers. Each custom header is a pair with a key and a value. -The **Service URL** displays constant that specifies the URL of the service endpoint: +The **Headers microflow** allows you to choose a microflow that returns a list of **System.HttpHeader**. See section [connection and headers microflow](#connection-and-headers-microflow) for details about how to create such a microflow. -* Click **Select** to choose another [constant](/refguide/constants/) for the service -* Click **Show** to open the **Constant** dialog box displaying the service URL or endpoint: +If the service uses a combination of a connection microflow, a headers microflow and a list of header that specify the same header, then the headers microflow overwrites the value of the list and the connection microflow overwrites both of their values. - {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/service-url.png" class="no-border" >}} +### Advanced -### Timeout +#### 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](/refguide/error-handling-in-microflows/). Default value: 300 seconds -### Proxy Configuration - -**Proxy configuration** allows you to configure a proxy for the request: +#### Error Handling Microflow -* **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 +When a call to the OData service fails, users see a generic error message. Create an [error-handling microflow](/refguide/error-handling-in-microflows/) to change this message. -{{% alert color="info" %}} -In most cases, this setting can be ignored and the default **Use app settings** can be used. -{{% /alert %}} +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. -### Authentication {#authentication} +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 **Use HTTP authentication** checkbox specifies if basic authentication should be used. If selected, specify the following details: +The microflow must return a `String` containing the error message. If it returns `empty`, the original generic message is used. -* **User name** – defines the user name that will be used for authentication -* **Password** – defines the password that will be used for authentication +Note for developers of Java actions: the message returned by the error handling microflow can be caught as a [UserException](https://apidocs.rnd.mendix.com/11/runtime/com/mendix/systemwideinterfaces/core/UserException.html). -Input these as a string with single quotes. +### Connection microflow and headers microflow{#connection-and-headers-microflow} -In addition to basic authentication, you can also use custom authentication. For more information, see the [HTTP Headers](#http-headers) section below. +Choose a microflow that returns one of the following options: -### HTTP Headers {#http-headers} +- A **System.ConsumedODataConfiguration** object with associated **System.HttpHeader** objects (for **Configuration microflow**) +- A list of **System.HttpHeader** objects (for **Headers microflow**) -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. +This microflow may take a parameter of type **System.HttpResponse**. The microflow is called every time a request is made. Initially, the HTTP response parameter will be empty. If the service responds with `401 Unauthorized`, the microflow is called with that HTTP response and another call is made with the new HTTP headers. -If the service uses a configuration microflow or a headers microflow that specifies a different value for the header, then that value overrides the value specified in this list. +{{% alert color="info" %}} +Custom authentication can be done with the microflow where the authentication value is retrieved (such as SSO). For more information on access and authentication, see [Using Custom HTTP Header Validation for Published Entities](/refguide/security-shared-datasets/#http-header-validation) in _Security and Shared Datasets_. +{{% /alert %}} -### Error Handling Microflow +#### Authenticating with Mendix SSO {#authenticate-mendix-sso} -When a call to the OData service fails, users see a generic error message. Create an [error-handling microflow](/refguide/error-handling-in-microflows/) to change this message. +{{% alert color="warning" %}} +The Mendix SSO module is deprecated as of May 1, 2026. For new implementations, it is recommended to configure custom authentication using [OIDC SSO](/appstore/modules/oidc/), [SAML](/appstore/modules/saml/), or [LDAP](/appstore/modules/ldap/) modules. +{{% /alert %}} -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. +Publishers can set up [custom authentication](/refguide/published-odata-services/#authentication-microflow) using [Mendix SSO](/appstore/modules/mendix-sso/) module. For more information, see the [Mendix SSO](/refguide/published-odata-services/#authentication-mendix-sso) section of _Published OData Services_. -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`. +Consumers of an OData service that is set up with Mendix SSO authentication can use the **CreateAccessTokenAuthorizationHeaderList**. -The microflow must return a `String` containing the error message. If it returns `empty`, the original generic message is used. +To learn more about how to publish an OData service with authentication (Mendix SSO, or other methods), see the [Authentication Methods](/refguide/published-odata-services/#authentication-methods) section of _Published OData Services_. -Note for developers of Java actions: the message returned by the error handling microflow can be caught as a [UserException](https://apidocs.rnd.mendix.com/11/runtime/com/mendix/systemwideinterfaces/core/UserException.html). +To learn more about using external entities with security enabled (in production environments), see the [Authentication](/refguide/external-entities/#authentication) section of _External Entities_. ### Metadata @@ -131,11 +145,11 @@ To open the **Metadata Editor**, click **Update**. In the editor, you can specif 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 +- **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](/catalog/manage/search/#service-details) in the details of a data source in the [Catalog](https://catalog.mendix.com/) and paste that value. + 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](/catalog/manage/search/#service-details) in the details of a data source in the [Catalog](https://catalog.mendix.com/) 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. @@ -151,20 +165,20 @@ Click the **Properties** tab for the consumed OData service which displays the p {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/properties-tab.png" width="300" class="no-border" >}} -* **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) +- **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) #### 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 `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](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody) in the OData specification. +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](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody) in the OData specification. ## Updating or Switching a Consumed OData Service {#updating} @@ -216,7 +230,7 @@ When a change in the contract at a consumed endpoint is detected (possibly due t 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](/refguide/consumed-odata-services/#consumed-odata-service-limitations) section of *Consumed OData Services* to read about known update limitations. +See the [Limitations](/refguide/consumed-odata-services/#consumed-odata-service-limitations) section of _Consumed OData Services_ to read about known update limitations. ##### Integration Pane @@ -224,9 +238,9 @@ In the [Integration pane](/refguide/integration-pane/), search results, and in t {{< figure src="/attachments/refguide/modeling/menus/view-menu/integration-pane/update-available.png" alt="Integration pane update" class="no-border" width="300" >}} -* The service version that is currently consumed is shown (in this example **1.2.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. -* When the Integration pane is showing search results, the displayed elements represent the assets available in the new version of the service that is found in the Catalog. When it is not showing search results, it shows the elements available for the currently consumed version of the service. +- The service version that is currently consumed is shown (in this example **1.2.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. +- When the Integration pane is showing search results, the displayed elements represent the assets available in the new version of the service that is found in the Catalog. When it is not showing search results, it shows the elements available for the currently consumed version of the service. ##### Update Service Dialog Box @@ -252,19 +266,19 @@ In the following example, the consumed **SalesOrders** service version **1.0.0** To consume the service deployed to the **Acceptance environment**, follow these steps: -1. Click **Update** > **Switch** on the **Consumed OData Service** document: +1. Click **Update** > **Switch** on the **Consumed OData Service** document: - {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/salesorders-header.png" alt="major change environment" class="no-border" >}} + {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/salesorders-header.png" alt="major change environment" class="no-border" >}} 2. On the **Switch** dialog box, from the drop-down list, select the service you want to consume from and click **Switch**: - {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/switch-dialog-box.png" alt="major change environment" width="700" class="no-border" >}} + {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/switch-dialog-box.png" alt="major change environment" width="700" class="no-border" >}} 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](/refguide/integration-pane/) will display that you are consuming from the selected environment: - {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/integration-pane-2.png" width="350" class="no-border" >}} + {{< figure src="/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/integration-pane-2.png" width="350" class="no-border" >}} ## Read More -* [Integration Pane](/refguide/integration-pane/) -* [Consumed OData Services](/refguide/consumed-odata-services/) +- [Integration Pane](/refguide/integration-pane/) +- [Consumed OData Services](/refguide/consumed-odata-services/) diff --git a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/authentication.png b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/authentication.png new file mode 100644 index 00000000000..7f34556a052 Binary files /dev/null and b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/authentication.png differ diff --git a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png index ff93f679d52..56df878f8d5 100644 Binary files a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png and b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/consumed-odata-service-screen.png differ diff --git a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/http-headers.png b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/http-headers.png new file mode 100644 index 00000000000..d4900b6ee2f Binary files /dev/null and b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/http-headers.png differ diff --git a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/proxy.png b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/proxy.png new file mode 100644 index 00000000000..74e28ecd7e2 Binary files /dev/null and b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/proxy.png differ diff --git a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/service-url.png b/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/service-url.png deleted file mode 100644 index f8817b91371..00000000000 Binary files a/static/attachments/refguide/modeling/integration/odata-services/consumed-odata-service/service-url.png and /dev/null differ