Merge branch '2024.3' into '2025.1'

modules/ROOT/pages/bonita-runtime-dependencies.adoc

@@ -1,4 +1,4 @@
-= Bonita Runtime dependencies (10.2.0.beta-02)
+= Bonita Runtime dependencies (10.2.0.beta-03)
 :page-aliases: ROOT:bonita-web-dependencies.adoc, ROOT:bonita-engine-dependencies.adoc
 :description: List all dependencies used by Bonita Runtime
 

modules/ROOT/pages/portal-js-dependencies.adoc

@@ -1,4 +1,4 @@
-= Dependencies for Bonita Portal-JS 10.2.0.beta-02
+= Dependencies for Bonita Portal-JS 10.2.0.beta-03
 :description: NodeJS Dependencies for Bonita Portal JS project 
 
 

modules/applications/applications-nav.adoc

@@ -22,7 +22,10 @@
    **** 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]
+    ***** xref:ui-builder/how-to-localize-your-application.adoc[Localize your application for various languages]
     ***** xref:ui-builder/how-to-use-mutable-js-variable.adoc[Use mutable JS variable]
+    ***** xref:ui-builder/common-apis-to-use.adoc[Common APIs to use]
+    ***** xref:ui-builder/how-to-retrieve-user-avatar.adoc[Retrieve user avatar image]
   *** xref:ui-builder/resources.adoc[Resources]
   *** xref:ui-builder/faq.adoc[FAQ]
  ** xref:ui-designer/uid-applications-index.adoc[Living applications with Bonita UID]

modules/applications/pages/ui-builder/bonita-ui-builder-best-practices.adoc

@@ -17,4 +17,19 @@ xref:ui-builder/how-to-avoid-unnecessary-information-messages.adoc[[.card-title]
 [.card.card-index]
 --
 xref:ui-builder/how-to-use-mutable-js-variable.adoc[[.card-title]#Use mutable JS variable# [.card-body.card-content-overflow]#pass:q[Learn how to update a JS variable to store and read data.]#]
+--
+
+[.card.card-index]
+--
+xref:ui-builder/how-to-localize-your-application.adoc[[.card-title]#Localize your application for various languages# [.card-body.card-content-overflow]#pass:q[Discover how to make your application accessible in multiple languages.]#]
+--
+
+[.card.card-index]
+--
+xref:ui-builder/common-apis-to-use.adoc[[.card-title]#Common APIs to use# [.card-body.card-content-overflow]#pass:q[Discover frequently used Bonita APIs to efficiently build complex applications in the UI Builder.]#]
+--
+
+[.card.card-index]
+--
+xref:ui-builder/how-to-retrieve-user-avatar.adoc[[.card-title]#Retrieve user avatar image# [.card-body.card-content-overflow]#pass:q[Discover how to fetch user avatar images and display them using the image widget.]#]
 --

modules/applications/pages/ui-builder/common-apis-to-use.adoc

@@ -0,0 +1,97 @@
+= Common APIs to use
+:description: Discover frequently used Bonita APIs to efficiently build complex applications in the UI Builder.
+
+{description}
+
+Bonita APIs combined with JS objects allow for building all kind of applications, such as: account management dashboard, custom CRM, HR Management tool, invoice processing dashboard, and many more.
+
+
+== Commonly used APIs
+
+While how JS objects are designed highly depends on your need, here are the most frequently used Bonita APIs you will very likely need for your applications.
+
+=== Session
+The session API is useful for retrieving session information for the current user.
+
+For example:
+
+    - GET | `/API/system/session/unusedId`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/Session/operation/getSession[session API documentation].
+
+=== Users
+The users API is useful for retrieving a list of users by applying pagination parameters and filters.
+
+For example:
+
+    - GET | `/API/identity/user?c=10&p=0&time=0&o=lastname+ASC&f=enabled=true`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/User/operation/searchUsers[users API documentation].
+
+=== Human tasks
+The human tasks API is useful to retrieve a list of human tasks by applying pagination parameters and filters.
+
+For example:
+
+    - GET | `/API/bpm/humanTask?c=10&p=0&f=state=ready&f=caseId=[caseId]`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/HumanTask/operation/searchHumanTasks[human tasks api documentation].
+
+=== User task context
+The user task context API provides the context for a specific user task identified by its id.
+
+For example:
+
+    - GET | `/bonita/API/bpm/userTask/[taskId]/context`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/UserTask/operation/getContextByUserTaskId[context by userTask id api documentation].
+
+=== Processes
+The process API is used to retrieve a list of process by applying pagination parameters and filters.
+
+For example:
+
+    - GET | `/bonita/API/bpm/process?c=10&p=0&f=name=[processName]&f=activationState=ENABLED` retrieves a list of specific process.
+    - POST | `/bonita/API/bpm/process/[processId]/instantiation` is used to instantiate a process.
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/Process/operation/searchProcesses[processes API documentation].
+
+=== Business data
+The business data is useful to find business data with pagination params and filters by invoking a `Named Query`. It allows to call either default or custom business data queries.
+
+For example:
+
+    - GET | `/API/bdm/businessData/[businessObject]?q=[query]&p=0&c=10&f=[filterString]=[filterParam]`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/BusinessDataQuery/operation/searchBusinessData[business data api documentation].
+
+=== Professional contact data
+The professional contact data is useful to retrieve the professional contact details of a user by their id.
+
+For example:
+
+    - GET | `/API/identity/professionalcontactdata/[userId]`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/ProfessionalContactData/operation/getProfessionalContactDataById[professional contact data api documentation].
+
+=== Group
+The group api is used to retrieve a list of groups by applying pagination params and filters.
+
+For example:
+
+    - GET | `/API/identity/group?c=10&p=0&d=parent_group_id&t=0&o=displayName%20ASC`
+
+For more detailed information, refer to the {openApiUrl}/latest/#tag/Group/operation/searchGroups[groups api documentation].
+
+=== Upload file
+The upload file api is used to upload a file of any type, typically before submitting a process or task form that includes a document in its contract.
+
+For example:
+
+    - POST | `/bonita/API/formFileUpload`
+
+For information on uploading multiple files, refer to the xref:how-to-upload-multiple-documents.adoc[upload multiple files.]
+
+
+[NOTE]
+In addition to the commonly used APIs, JS objects can also be created to meet specific application needs.

modules/applications/pages/ui-builder/faq.adoc

@@ -139,6 +139,10 @@ Yes, they are compatible with both deployment modes.
 Yes it is. Reach out to your customer service representative to explore how you can migrate to Bonita Cloud.
 
 
+=== Is it possible to deploy multiple UI Builder node instances for redundancy?
+No, the UI Builder node cannot be deployed with redundancy. Currently, only a single container instance is supported, which means multiple instances for redundancy are not allowed.
+
+
 === Can multiple users collaborate on the same local Bonita UI Builder development server?
 No, the local Bonita UI Builder server is mono-user, meaning it only supports one Bonita user account at a time. To collaborate, each user should run their own local server and work with a shared Git repository for syncing and integrating their changes.
 
@@ -201,4 +205,17 @@ These errors are likely related to your Bonita server being down.
 
 [.solution]#Solution#
 Ensure that your Bonita server is active and running.
+--
+
+[#DocumentViewerissue]
+[.troubleshooting-section]
+--
+[.symptom]
+The Document Viewer widget doesn't seem to be functioning as expected. How can I view my documents?
+
+[.cause]#Cause#
+The `Document Viewer` widget currently doesn't support the Bonita Document viewer links (formsDocumentImage).
+
+[.solution]#Solution#
+You can use an `Iframe` widget as an alternative solution.
 --

modules/applications/pages/ui-builder/how-to-localize-your-application.adoc

@@ -0,0 +1,107 @@
+= Localize your application for various languages
+:page-aliases: applications:how-to-localize-your-application.adoc
+:description: Discover how to make your application accessible in multiple languages.
+
+{description}
+
+* Difficulty: beginner
+* Prerequisites: have an application on Bonita UI Builder
+
+Suppose you're creating an application and want to allow users to easily switch between several languages by choosing a language option.
+While UI Builder currently doesn't have a built-in feature for making an application multilingual, the steps below describe the recommended way to do so.
+
+
+== Example
+
+image:ui-builder/guides/localize-your-app.gif[localize-your-app]
+
+We will cover below all the steps shown in the gif above.
+
+=== 1 Design the application's interface
+* Drag and drop a `Select` widget onto your interface, name it `SelectLanguage`, and configure the Source Data property as follows:
+
+[source, JS]
+----
+[
+  {
+    "key": "English",
+    "value": "en"
+  },
+  {
+    "key": "Français",
+    "value": "fr"
+  },
+  {
+    "key": "Spanish",
+    "value": "es"
+  }
+]
+----
+
+* Now, drag and drop a `Text` widget onto your interface and add a sentence into its `Text` property.
+For example, `This is a sample application to demonstrate the possibility of making it available in multiple languages.`
+
+
+=== 2 Define JS objects
+* Go to the JS section, create a new JavaScript object, and name it `localization`.
+* In the `localization` file, define JavaScript objects for each language to correspond with the values set for the `SelectLanguage` widget. Include the words or sentences along with their translations as key-value pairs for all languages, as shown in the code snippet below:
+
+[source, JS]
+----
+export default {
+	translations: {
+		en: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "This is a sample application to demonstrate the posibility of making it available in multi-languages."
+		},
+		fr: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "Il s'agit d'un exemple d'application visant à démontrer la possibilité de la rendre disponible en plusieurs langues."
+		},
+		es: {
+			"This is a sample application to demonstrate the possibility of making it available in multiple languages.": "Esta es una aplicación de muestra para demostrar la posibilidad de hacerlo disponible en varios idiomas."
+		}
+	}
+}
+----
+
+
+[NOTE]
+====
+Ensure that all language keys match the values set in the `SelectLanguage` source data, such as en, fr, and es, etc.
+====
+
+* To keep the codebase organized, define another JavaScript object and name it `i18n`.
+* Copy and paste the JavaScript code blocks provided below:
+
+[source, JS]
+----
+export default {
+	languageKeys: {},
+	onLanguageChange() {
+		this.languageKeys = localization.translations[SelectLanguage.selectedOptionValue];
+	},
+	setLangugeKey() {
+		this.languageKeys = localization.translations["en"];
+		return this.languageKeys;
+	}
+}
+----
+
+This JavaScript module manages language translations using the `languageKeys` property. The `onLanguageChange()` method updates `languageKeys` based on the selected language, while `setLangugeKey()` sets it to the default English translations and returns the updated object.
+
+[NOTE]
+====
+Ensure that the `Run on page load` setting is enabled for the `setLanguageKey` function.
+====
+
+
+=== 3 Bind JS objects to the widgets
+* Come back to the UI section and select the `SelectLanguage` widget.
+* Set its `Label` to `{{i18n.languageKeys["Select language"]}}`.
+* In the Events property, set `{{i18n.onLanguageChange();}}` to invoke the function when the language changes.
+* Then, select the text widget and set the `Text` property to `{{i18n.languageKeys["This is a sample application to demonstrate the possibility of making it available in multiple languages."]}}`.
+
+
+[NOTE]
+====
+Since the goal of this example is to provide best practices for managing several languages, it does not address cookies. It is of course possible to define JS objects that manage cookies according to your needs.
+====

modules/applications/pages/ui-builder/how-to-retrieve-user-avatar.adoc

@@ -0,0 +1,68 @@
+= Use Javascript to retrieve user avatar image
+:page-aliases: applications:how-to-retrieve-user-avatar.adoc
+:description: Discover how to fetch user avatar images and display them using the image widget.
+
+{description}
+
+* Difficulty: beginner
+* Prerequisites: have an application on Bonita UI Builder
+
+Assume we want to extract an image path from our API response and display a user avatar by binding it to an image widget.
+This can be done by creating a JavaScript function that constructs the URL for the 'icon' parameter.
+
+== Example
+
+image:ui-builder/guides/user-list.png[user-list]
+
+=== 1. Create an API query
+* Navigate to the `Queries` section, create a new query/API, name it `getUsers` and configure as shown in the image below:
+
+image:ui-builder/guides/query-get-users.png[query-get-users]
+
+The `getUsers` query returns a list of users that includes an image path for an avatar icon if available; otherwise, it provides a default user image icon.
+
+=== 2. Create JS functions
+
+* Go to the `JS` section, create a new JS object named `userAvatar`, and implement the function as provided below:
+
+[source,JS]
+----
+export default {
+    getIconFullURL(icon) {
+		let currentDomain = appsmith.URL.protocol + "//" + appsmith.URL.hostname;
+
+		if (appsmith.URL.port) {
+			currentDomain += ":" +  appsmith.URL.port;
+		}
+		return currentDomain + "/bonita/portal-theme/" + icon;
+	}
+}
+----
+
+The provided code snippet above exports an object containing a `getIconFullURL` method that builds a complete URL for an icon by combining the current domain's protocol, hostname, and port with a specified icon path.
+It appends the icon path to the `/bonita/portal-theme/` directory on the server. This method ensures that the generated URL correctly points to the icon on the same server where the application is hosted.
+
+
+=== 3. Design the user interface
+* Navigate to the `UI` section, drag and drop a text widget onto the interface, and set its text to 'Users'.
+* Next, drag and drop a `list` widget onto the interface and bind it to the `getUsers` query that was created earlier:
+
+image:ui-builder/guides/user-list-widget.png[user-list-widget]
+
+* Since the list widget by default includes text widgets and an image widget for each list item, we will use these default widgets to bind the list items.
+* Select a text widget and bind it to the `firstname` of a user in the list. For instance, use `First name {{ currentItem.firstname }}`:
+
+image:ui-builder/guides/firstname.png[firstname]
+
+* Similarly, bind the `lastname` and `username` to the other text widgets.
+For example use `Last name {{ currentItem.lastname }}` and `Username {{ currentItem.username }}`.
+
+* Now, select the image widget and call the Javascript function created previously to bind it to the user's avatar icon.
+For example, user `{{ userAvatar.getIconFullURL(currentItem.icon) }}`:
+
+image:ui-builder/guides/user-avatar.png[user-avatar]
+
+[NOTE]
+====
+Feel free to adjust the UI according to your preferences.
+====

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

@@ -19,6 +19,16 @@ xref:how-to-share-data-across-pages.adoc[[.card-title]#How to share data across
 xref:how-to-control-visibility-of-widgets.adoc[[.card-title]#How to control visibility of your widgets# [.card-body.card-content-overflow]#pass:q[Learn how to set conditions to make your widgets visible or not]#]
 --
 
+[.card.card-index]
+--
+xref:how-to-handle-pagination.adoc[[.card-title]#How to handle server-side pagination# [.card-body.card-content-overflow]#pass:q[Learn how to handle server-side pagination and optimize performance]#]
+--
+
+[.card.card-index]
+--
+xref:how-to-create-editable-tables.adoc[[.card-title]#How to create editable and powerful Tables# [.card-body.card-content-overflow]#pass:q[Learn how to configure tables from which you can edit Bonita data, display dynamic values, color cells]#]
+--
+
 [.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.]#]