From 0d1a455a78200a6d2afa6ac6f66e94b89a94122f Mon Sep 17 00:00:00 2001 From: Joost Verhoog Date: Fri, 30 Oct 2026 15:26:24 +0100 Subject: [PATCH] Document GET microflow handling for readable published OData entities Add the microflow parameters, count behavior, and security note to the Readable section of Published OData Entity in refguide and refguide10. Fix typos and the duplicate anchor in the refguide9 wrap-services page. --- .../published-odata-entity.md | 42 ++++++++++++++++++- .../published-odata-entity.md | 42 ++++++++++++++++++- .../odata-services/wrap-services-odata.md | 22 +++++----- 3 files changed, 93 insertions(+), 13 deletions(-) diff --git a/content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/published-odata-entity.md b/content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/published-odata-entity.md index 1af44adfb8c..89b0f7932f2 100644 --- a/content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/published-odata-entity.md +++ b/content/en/docs/refguide/modeling/integration/odata-services/published-odata-services/published-odata-entity.md @@ -121,7 +121,9 @@ In the publishing app, you can use a validation message action to report a valid There are two options to handle an incoming GET request for a published entity: 1. **Read from database** – This action will parse the incoming query to a database query and retrieve the data from the database. This is the default action for **Readable** section. This action is not applicable to non-persistable entities, because non-persistable entities cannot be retrieved from the database. -2. **Call a microflow** – This action will call a microflow. You can specify your custom logic in this microflow to return a list of objects that correspond to the incoming request. +2. **Call a microflow** – This action will call a microflow. You can specify your custom logic in this microflow to return a list of objects that correspond to the incoming request. For more information, see [Handling a Request with a Microflow](#handle-get-request). + +The resulting list of objects from either action is transformed into an OData payload. If this fails, the service returns a [status code](/refguide/published-odata-services/#status-codes) of `500`. You can also set the [query options](#query-options) for each request. @@ -129,6 +131,44 @@ A published entity is readable by default. It is possible to disable this capabi When **Readable** is enabled, you can configure how data is queried in the [exposed data](#exposed-data) section. Note that **Readable** must be enabled in order to enable the other capabilities. +#### Handling a Request with a Microflow {#handle-get-request} + +The microflow is executed when a consumer sends a request to the service endpoint. The microflow takes care of the following: + +1. Parse the incoming OData query. +2. Decide what data needs to be collected. +3. Retrieve the required data. +4. Retrieve the count when requested, storing the count value in the **ODataResponse** object. +5. Return a list of objects that matches the published entity. + +{{% alert color="info" %}} +When you use a microflow to provide data, any security constraints are applied to the result of the microflow. +{{% /alert %}} + +The microflow accepts the following optional parameters: + +* **HttpRequest** – The first parameter is an HTTP request of the entity type [System.HttpRequest](/refguide/http-request-and-response-entities/). + + When a consumer sends a request to the published OData service, the `HttpRequest` string attribute `Uri` contains the OData query that the consumer requested. Based on that information, the microflow needs to decide what to return. For more information about how OData v4 requests work, see [OData v4.0. Part 2: URL Conventions Plus Errata 03](https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html). + +* **ODataResponse** – The second parameter is an OData response of the entity type **System.ODataResponse**. + + The **ODataResponse** entity has a **Count** attribute where you can store the count value. + + OData has two different count types: + + 1. **Count as a request** – Use this when the consumer is only interested in the number of objects and not the objects themselves. + + For example, the request `persons/$count?$filter=name eq 'John'` returns the number of people named John. + + If **ODataResponse** is present as a microflow parameter, the **Count** attribute value is returned regardless of the resulting list of objects. Otherwise, the objects in the resulting list are counted. + + 2. **Inline count in the request** – Use this when the consumer is interested in the total number of objects while retrieving some of the objects. + + For example, the request `persons?$count=true&$skip=5&$top=5` returns an OData payload with a maximum of five objects, and a count of the total number of objects that would have been returned if the request did not include `$skip` and `$top`. The count is included in the payload. This is useful when paging through all the objects. + + If **ODataResponse** is present as a microflow parameter, the **Count** attribute value is returned regardless of the resulting list of objects. Otherwise, the count is `-1`, which means not defined and is the default value. A **Count** value of `0` means that there are no records. + #### Query Options {#query-options} Select the options to include for the **Readable** OData/GraphQL capability: diff --git a/content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/published-odata-entity.md b/content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/published-odata-entity.md index 59887f2f837..e4634285b14 100644 --- a/content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/published-odata-entity.md +++ b/content/en/docs/refguide10/modeling/integration/odata-services/published-odata-services/published-odata-entity.md @@ -125,7 +125,9 @@ In the publishing app, you can use a validation message action to report a valid There are two options to handle an incoming GET request for a published entity: 1. **Read from database** – This action will parse the incoming query to a database query and retrieve the data from the database. This is the default action for **Readable** section. This action is not applicable to non-persistable entities, because non-persistable entities cannot be retrieved from the database. -2. **Call a microflow** – This action will call a microflow. You can specify your custom logic in this microflow to return a list of objects that correspond to the incoming request. +2. **Call a microflow** – This action will call a microflow. You can specify your custom logic in this microflow to return a list of objects that correspond to the incoming request. For more information, see [Handling a Request with a Microflow](#handle-get-request). + +The resulting list of objects from either action is transformed into an OData payload. If this fails, the service returns a [status code](/refguide10/published-odata-services/#status-codes) of `500`. You can also set the [query options](#query-options) for each request. @@ -137,6 +139,44 @@ When **Readable** is enabled, you can configure how data is queried in the [expo Support for publishing entities without the **Readable** capability was introduced in Studio Pro [10.8.0](/releasenotes/studio-pro/10.8/). {{% /alert %}} +#### Handling a Request with a Microflow {#handle-get-request} + +The microflow is executed when a consumer sends a request to the service endpoint. The microflow takes care of the following: + +1. Parse the incoming OData query. +2. Decide what data needs to be collected. +3. Retrieve the required data. +4. Retrieve the count when requested, storing the count value in the **ODataResponse** object. +5. Return a list of objects that matches the published entity. + +{{% alert color="info" %}} +When you use a microflow to provide data, any security constraints are applied to the result of the microflow. +{{% /alert %}} + +The microflow accepts the following optional parameters: + +* **HttpRequest** – The first parameter is an HTTP request of the entity type [System.HttpRequest](/refguide10/http-request-and-response-entities/). + + When a consumer sends a request to the published OData service, the `HttpRequest` string attribute `Uri` contains the OData query that the consumer requested. Based on that information, the microflow needs to decide what to return. For more information about how OData v4 requests work, see [OData v4.0. Part 2: URL Conventions Plus Errata 03](https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html). + +* **ODataResponse** – The second parameter is an OData response of the entity type **System.ODataResponse**. + + The **ODataResponse** entity has a **Count** attribute where you can store the count value. + + OData has two different count types: + + 1. **Count as a request** – Use this when the consumer is only interested in the number of objects and not the objects themselves. + + For example, the request `persons/$count?$filter=name eq 'John'` returns the number of people named John. + + If **ODataResponse** is present as a microflow parameter, the **Count** attribute value is returned regardless of the resulting list of objects. Otherwise, the objects in the resulting list are counted. + + 2. **Inline count in the request** – Use this when the consumer is interested in the total number of objects while retrieving some of the objects. + + For example, the request `persons?$count=true&$skip=5&$top=5` returns an OData payload with a maximum of five objects, and a count of the total number of objects that would have been returned if the request did not include `$skip` and `$top`. The count is included in the payload. This is useful when paging through all the objects. + + If **ODataResponse** is present as a microflow parameter, the **Count** attribute value is returned regardless of the resulting list of objects. Otherwise, the count is `-1`, which means not defined and is the default value. A **Count** value of `0` means that there are no records. + #### Query Options {#query-options} Select the options to include for the **Readable** OData/GraphQL capability: diff --git a/content/en/docs/refguide9/modeling/integration/odata-services/wrap-services-odata.md b/content/en/docs/refguide9/modeling/integration/odata-services/wrap-services-odata.md index b17d2212706..6e32f4fb833 100644 --- a/content/en/docs/refguide9/modeling/integration/odata-services/wrap-services-odata.md +++ b/content/en/docs/refguide9/modeling/integration/odata-services/wrap-services-odata.md @@ -7,7 +7,7 @@ weight: 80 ## Introduction -Features released in Studio Pro [9.17](/releasenotes/studio-pro/9.17/) expand on existing OData capabilities in Studio Pro. These features allow you to wrap any non-OData service, API, or database with OData, ensuring compatibility with [external entities](/refguide9/external-entities/) and the [Catalog](/catalog/)). +Features released in Studio Pro [9.17](/releasenotes/studio-pro/9.17/) expand on existing OData capabilities in Studio Pro. These features allow you to wrap any non-OData service, API, or database with OData, ensuring compatibility with [external entities](/refguide9/external-entities/) and the [Catalog](/catalog/). You can also use these features to more easily [build connectors](/appstore/creating-content/connector-guide-build/) that access external data. This set of features adds to the tools described in [Introducing the Mendix Connector Kit](https://www.mendix.com/blog/introducing-mendix-connector-kit/), and are collectively referred to as *Connector Kit 2.0*. @@ -50,7 +50,7 @@ Publishing a non-persistable entity as a published OData resource is supported f ## Data Sources for Published OData Resources {#odata-data-sources} -In Studio Pro, you can expose entities as OData resources by adding them to a published OData service. You can expose any number of related resources in a published OData service by using a microflow that determines the result of the incoming request. This is now possible for the [Readable](/refguide9/published-odata-resource/#readable) capability of your service you can define how your resources should be retrieved and stored. +In Studio Pro, you can expose entities as OData resources by adding them to a published OData service. You can expose any number of related resources in a published OData service by using a microflow that determines the result of the incoming request. This is possible for the [Readable](/refguide9/published-odata-resource/#readable) capability of your service, where you can define how your resources should be retrieved and stored. When a consuming app reads your published OData service, it sends a GET request. You can handle an incoming GET request for an OData resource in the following ways: @@ -91,7 +91,7 @@ When you use a microflow to provide data, any security constraints are applied t * **HttpRequest** – The first accepted parameter is an HTTP request of the entity type **System.HttpRequest**. This parameter is optional. - When a consumer sends a request to the published OData service, the `HttpRequest` string attribute *Uri* will contain the OData query that consumer requested. Based on that information, the microflow needs to decide what should be returned. For more information on how an OData v4 requests work, see [OData v4.0. Part 2: URL Conections Plus Errata 03](https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html). + When a consumer sends a request to the published OData service, the `HttpRequest` string attribute `Uri` will contain the OData query that consumer requested. Based on that information, the microflow needs to decide what should be returned. For more information on how an OData v4 requests work, see [OData v4.0. Part 2: URL Conventions Plus Errata 03](https://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html). * **ODataResponse** – The second accepted parameter is an OData response of the entity type **System.ODataResponse**. This parameter is optional. @@ -109,11 +109,11 @@ When you use a microflow to provide data, any security constraints are applied t 1. **Inline count in the request** – Use this when the consumer is interested in the total number of objects while retrieving some of the objects. - For example, consider the following request: `persons?$count=true&$skip=5&top=5` + For example, consider the following request: `persons?$count=true&$skip=5&$top=5` - This returns an OData payload with maximum give objects, and a count of the total number of objects that would have been returned if the request did not include $skip and $top. The count information will be included in the payload. This information is useful when paging through all the objects. + This returns an OData payload with maximum five objects, and a count of the total number of objects that would have been returned if the request did not include $skip and $top. The count information will be included in the payload. This information is useful when paging through all the objects. - If the **ODataResponse** is present as a microflow parameter, then it will return the **Count** attribute value regardless of the result list of objects. Otherwise, it will return -1 for not defined, which is the default value. A **Count** value of 0 means that there no record. + If the **ODataResponse** is present as a microflow parameter, then it will return the **Count** attribute value regardless of the result list of objects. Otherwise, it will return -1 for not defined, which is the default value. A **Count** value of 0 means that there are no records. {{% alert color="info" %}} In Studio Pro [9.16](/releasenotes/studio-pro/9.16/) and below, the inline count value will be retrieved from the count microflow. For Studio Pro [9.17](/releasenotes/studio-pro/9.17/) and above, the count value can be stored in the `ODataResponse` object. @@ -125,7 +125,7 @@ Select which attribute(s) to use as a [key](/refguide9/published-odata-resource/ To learn more about selecting a key, see the [Key](/refguide9/published-odata-resource/#key) section of *Published OData Resource*. -### Selecting Attributes as a Key {#select-key} +### Selecting Attributes as a Key {#select-attributes-key} To select different attributes as a key, do the following: @@ -200,7 +200,7 @@ Set up an X client module that allows users to input an X ID and communicates to {{< figure src="/attachments/refguide9/modeling/integration/wrap-services-odata/showuserpage-microflow.png" alt="Microflow that handles TwitterClientInput request and shows a page." class="no-border" >}} -5. On the **XPage**, use a **Data Grid**, and pull data **by Association** from the to get the tweets and followers connected to the user. +5. On the **XPage**, use a **Data Grid**, and pull data **by Association** from the **User** entity to get the tweets and followers connected to the user. #### Parsing the URI @@ -214,18 +214,18 @@ Ensure that you have created microflows for all entities used in your connector. ## Updatable Operational Data Stores {#operational-data-stores} -Wrapped OData APIs can function as an operational data store, or as a [Data Layer](/refguide9/create-a-basic-data-layer/) for other Mendix apps. For example, you have one Mendix app where you define a central data model that is being used by multiple frontend apps. This central app gets data from different backend systems, caches it, and makes it available as a unified model to the frontend apps. With OData, can provide full read-write APIs to your frontend apps. To ensure data consistency, you can use [OData as a data source microflows](#odata-data-sources) to update your backend systems when a front-end app changes data through an OData API. +Wrapped OData APIs can function as an operational data store, or as a [Data Layer](/refguide9/create-a-basic-data-layer/) for other Mendix apps. For example, you have one Mendix app where you define a central data model that is being used by multiple frontend apps. This central app gets data from different backend systems, caches it, and makes it available as a unified model to the frontend apps. With OData, you can provide full read-write APIs to your frontend apps. To ensure data consistency, you can use [OData as a data source microflows](#odata-data-sources) to update your backend systems when a front-end app changes data through an OData API. Operational data stores are often used to unify and cache external data used by multiple apps. Reasons for this include the following: -* Service APIs do not fit well with interactive use by frontend apps (no sorting,paging, filtering available on the APIs). +* Service APIs do not fit well with interactive use by frontend apps (no sorting, paging, filtering available on the APIs). * You want to centrally manage security on the data, instead of handling this in every frontend app. * You want to simplify the data model by unifying data from different services. To implement a low-code operational data store, include these steps: * Define a unified model using persistable entities. -* Cache data in a persistable entity. When you call the OData source, it will any updates since it was last called, and will retrieve older records from a local database. +* Cache data in a persistable entity. When you call the OData source, it will retrieve any updates since it was last called, and will retrieve older records from a local database. * Expose the unified model with OData, including write-back logic in your microflows. For general information on building connectors, see the [Build Connectors](/appstore/creating-content/connector-guide-build/) guide.