docs: Add new UIB guide for query dependencies

modules/applications/applications-nav.adoc

@@ -22,6 +22,7 @@
    **** xref:ui-builder/how-to-control-visibility-of-widgets.adoc[How to control visibility of your widgets]
    **** xref:ui-builder/how-to-handle-pagination.adoc[How to handle server-side pagination]
    **** xref:ui-builder/how-to-create-editable-tables.adoc[How to create editable and powerful Tables]
+   **** xref:ui-builder/how-to-handle-queries-dependency.adoc[How to handle dependencies between queries]
    **** xref:ui-builder/how-to-upload-multiple-documents.adoc[Upload multiple documents simultaneously]
    **** xref:ui-builder/bonita-ui-builder-best-practices.adoc[Best practices]
     ***** xref:ui-builder/how-to-avoid-unnecessary-information-messages.adoc[Avoid unnecessary information messages]

modules/applications/pages/ui-builder/how-to-handle-queries-dependency.adoc

@@ -0,0 +1,82 @@
+= How to handle queries dependency
+:page-aliases: applications:how-to-handle-queries-dependency.adoc
+:description: Learn how to handle dependencies between queries
+
+{description}
+
+* Difficulty: intermediate
+* Estimated time: 10 minutes
+
+If your application needs to run several API calls and some of them depend on the result of others,
+you may have issues with the order of execution of the API calls.
+
+For example, if you want to get the list of users and display the manager of the first one in the list, you need to make two API calls:
+
+* One to get the list of users
+* One to get the manager of the first user (so that take as parameter the manager id of the first user from the first API call)
+
+Note: make sure the first user has a manager. If not, choose another user.
+
+Since you want to get these information on page load, you *may* have an issue if the second API call is executed *before* the first one is done.
+
+To handle this kind of situation, let's do the following.
+
+== 1. Create the API requests
+
+Go to the `Queries` tab and create a first Bonita query that will fetch the users:
+
+* `Name`: getUsers
+* `Method`: GET
+* `URL`: /bonita/API/identity/user
+* `Params`:
+    - `Key`: p
+    - `Value`: 0
+    - `Key`: c
+    - `Value`: 20
+* `Settings`:
+    - `Run API on page load`: true
+
+From the `Settings` tav, enable the
+
+Then, create a second Bonita query that will fetch the manager of the first user:
+
+* `Name`: getManagerOfFirstUser
+* `Method`: GET
+* `URL`: /bonita/API/identity/user/{{getUsers.data[0].manager_id}}
+* `Settings`:
+    - `Run API on page load`: true
+
+
+== 2. Configure the interface
+
+On the interface, drag and drop a Text widget and set its text to `{{First user: {{getUsers.data[0].lastname}}}}`.
+
+Then, drag and drop a second Text widget and set its text to `{{Manager: {{getManagerOfFirstUser.data.lastname}}}}`.
+
+Reload the page and *if the second query is called first* you should get an error: `The action "getManagerOfFirstUser" has failed`.
+
+To solve this (potential) issue, we will create a JS Object that will run the queries in the right order.
+
+== 3. Create a JS object
+
+Go to the `JS` tab (between `Queries` and `UI`), create a new JS Object called “runQueries” and copy paste the following code:
+
+[source, JS]
+----
+export default {
+    runQueries: async () => {
+            await getUsers.run();
+            getManagerOfTheFirstUser.run();
+    }
+}
+----
+
+The first query is called synchronously (`await` keyword), and the second one is called only when the first one is done.
+
+Now, from the `Settings` tab, enable the `Run on page load` option.
+
+== 4. Disable the running on page load for the queries
+
+For the 2 queries, from the `Settings` tab, set the `Run API on page load` option to `false`.
+
+Reload the page: you are now sure that the page will display the first user and its manager!

modules/applications/pages/ui-builder/how-tos-builder.adoc

@@ -29,6 +29,11 @@ xref:how-to-handle-pagination.adoc[[.card-title]#How to handle server-side pagin
 xref:how-to-create-editable-tables.adoc[[.card-title]#How to create editable and powerful Tables# [.card-body.card-content-overflow]#pass:q[Configure tables to edit data, display dynamic values, color cells]#]
 --
 
+[.card.card-index]
+--
+xref:how-to-handle-queries-dependency.adoc[[.card-title]#How to handle dependencies between queries# [.card-body.card-content-overflow]#pass:q[Learn how to handle dependencies for queries running on page load]#]
+--
+
 [.card.card-index]
 --
 xref:how-to-upload-multiple-documents.adoc[[.card-title]#Upload multiple documents simultaneously# [.card-body.card-content-overflow]#pass:q[Learn how to upload multiple documents simultaneously]#]