[UIA-1455] Add global inbox documentation

content/en/docs/marketplace/platform-supported-content/modules/global-inbox.md

@@ -0,0 +1,143 @@
+---
+title: "Global Inbox"
+url: /appstore/modules/global-inbox/
+description: "Describes the configuration and usage of the Global Inbox and Global Inbox Connector modules, which are available in the Mendix Marketplace."
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. 
+---
+
+## Introduction
+
+The **Global Inbox** enables centralized task management across multiple applications by introducing two modules: the [Global Inbox](link) and the [Global Inbox Connector](link).
+
+The **Global Inbox** module offers a centralized task inbox that aggregates workflow tasks from multiple applications, allowing users to view and manage all their tasks in a single overview.
+
+Applications that want their workflow tasks to appear in the **Global Inbox** are called Publisher Applications. These applications use the **Global Inbox Connector** to publish task-related events. The connector is specifically designed for Mendix Workflows. Task updates are communicated via Mendix Business Events, that carry information about workflow changes such as task creation, assignment, updates, and completion.
+
+The **Global Inbox** is designed to:
+* Provide a single Task Inbox for tasks across multiple applications.
+* Reduce complexity by consolidating tasks from different applications.
+* Support real-time synchronization of task status, assignments, and workflow progress.
+* Improve user productivity and visibility by centralizing task management.
+
+While the architecture can support broader use cases, the current scope focuses on tasks generated by Mendix built-in workflows. 
+
+## Features
+
+* Consists of two Mendix modules: [Global Inbox](link) and [Global Inbox Connector](link)
+* Intended for Mendix Applications that use [Mendix Workflows](https://docs.mendix.com/refguide/workflows/) to manage workflows. Support for non-Mendix workflows will be introduced at a later stage.
+* Redirects users to Publisher Applications to act on the user task.
+
+{{% alert color="info" %}}For Global Inbox version 2.4.0 and above, attachments are (an optional) part of comments. This means that the WorkflowAttachment entity is associated with the WorkflowComment entity. Security settings for the WorkflowAttachment entity are based on the workflows in which a user is involved, since the context of a specific workflow is not known in advance in Workflow Commons. If you would like to set custom security for attachments, you need to configure the attachment entity in your domain model and associate it with the workflow context entity of the workflow. {{% /alert %}}
+
+## Limitations
+
+* **Global Inbox** does not support Workflow Groups at the moment. This will be introduced at a later stage.
+* The beta version of **Global Inbox** has limited support for error handling. Any exceptions that occur in a microflow after updating a user task (or other Workflow-related entity) in the same microflow (for example, updating the targeted users or due date) might result in data becoming out of sync. This is a temporary limitation that will be resolved in an upcoming version.
+* Workflows and tasks that are modeled in the same app that includes the Global Inbox module will **not** be available in the Global Inbox. The Global Inbox app only consumes and displays workflow instances from other Mendix applications.
+
+## Prerequisites
+
+* Mendix 11.6.0 or above
+* Single Sign-On (SSO) is required for user authentication, as the User.Name attribute is used to match users across the Global Inbox and Publisher Applications. For security reasons, ensure that the username is not modifiable by the end user and is only set by the SSO provider. 
+
+## Dependencies
+
+* [Mendix Business Events](https://marketplace.mendix.com/link/component/202649)
+* [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907)
+    * Requires a license for apps running on Mendix Cloud
+    * Alternatively, you can use [your own Kafka cluster](https://docs.mendix.com/appstore/services/business-events-deployment/#byok)
+* [Atlas Core](https://marketplace.mendix.com/link/component/117187) (v4.0.0 or higher)
+* [Atlas Web Content](https://marketplace.mendix.com/index3.html) (v4.0.0 or higher)
+* [Data Widgets](https://marketplace.mendix.com/link/component/116540)
+
+
+## Architecture
+
+The **Global Inbox** operates on an event-driven architecture: 
+
+### Components:
+
+* [Global Inbox](link): The Global Inbox is a module that contains the Global Task Inbox page, which aggregates workflow tasks from multiple Publisher Applications into a single overview. It serves as a centralized system that consumes business events and updates the Global Task Inbox accordingly. The page is read-only. Users cannot act on tasks directly. Users can only click on tasks to navigate to the corresponding page in the Publisher Application. It includes three tabs:
+    1. My open tasks shows the tasks assigned to current user. 
+    2. All open tasks is a list of tasks current user could pick up. 
+    3. Unassigned tasks shows all unassigned tasks. 
+
+[Global Inbox Connector Module](link): A module that can be imported into each Publisher Application and contains the functionality to publish task updates through Mendix Business Events. It is intended for Mendix Publisher Applications that use Mendix Workflows to manage workflows.
+
+[Mendix Business Events](https://marketplace.mendix.com/link/component/202649): Events that carry information about user tasks and workflow changes, such as task creation, updates, or completion. All relevant information about  Business Events can be found in the Mendix Business Events documentation. The Global Inbox owns the definition of the Business Events, and the Publisher Applications publishes them. 
+
+[Mendix Event Broker](https://marketplace.mendix.com/link/component/202907): The Event Broker is used to deliver all Business Events from Publisher Applications to the Global Inbox. You can use [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) (requires a license) or [bring your own Kafka](https://docs.mendix.com/appstore/services/business-events-deployment/#byok) cluster.
+
+
+{{< figure src="/attachments/appstore/platform-supported-content/modules/global-inbox/high-level-architecture.png" alt="configuration" max-width=90% >}} 
+
+### Event Flow:
+
+* Publisher App Registration: Each publisher application registers with the Global Inbox by publishing a PublisherAppRegisteredEvent. This ensures the Global Inbox knows which apps are available to send task events.
+
+* Task Update & Event Publication: When a workflow or task is created, updated, or completed in a publisher application that includes the Global Inbox Connector, the connector publishes the following events:
+
+    * WorkflowUpdatedEvent – triggered when the workflow is updated.
+
+    * UserTaskUpdatedEvent – triggered when a user task is updated.
+
+    * UserTaskEndedEvent – triggered when a user task is completed or aborted.
+
+    * UserTaskOutcomeSelectedEvent – triggered when a user completes a task by selecting an outcome.
+
+* Event Consumption: The Global Inbox consumes these events and updates or creates the corresponding task entries in the central task list.
+
+* Task Visibility & Navigation: Tasks become visible in the Global Inbox. Users can click a button to navigate directly to the corresponding task page in the Publisher Application to take action.
+
+## Set Up Guide
+
+### Setup Global Inbox
+
+1. Import the [Global Inbox module](link) into the application that will serve as the central task overview. This application aggregates tasks from multiple Publisher Applications and provides a single interface where users can view all active tasks. It acts as the consumer of task events and maintains the consolidated task list. 
+2. Add the **GlobalTaskInbox** page to your navigation. The **GlobalTaskInbox** page is located at: **GlobalInbox** > **UseMe** > **Pages** > **GlobalTaskInbox**. This page can be accessed by users, allowing them to view all tasks from different applications.
+3. Add the User module roles to the required App roles.
+4. Deploy and configure constants
+    * The **CleanupEventsAfterDays** constant can be configured at: **UseMe** > **Configuration** > **CleanupEventsAfterDays**. All business events use their own entities to store data for consumption. For example, **CBE_UserTaskUpdatedEvent** stores data for the User Task Updated event. The **CleanupEventsAfterDays** setting is configurable and determines how long event data is retained. Data older than the specified number of days is automatically cleaned up. The default value is set to 30 days.
+    * **DueDateExpirationInDays** constant to configure the period in days for which the user tasks are to be considered almost due with visual indicators in Global Task Inbox page. The default value is set to 2 days. You should set the value based on your business needs.
+
+{{% alert color="info" %}}Make sure the Global Inbox app is deployed and running before deploying the Publisher Applications.{{% /alert %}}
+
+### Setup Global Inbox Connector
+
+1. Import the [Global Inbox Connector](link) module. This module is responsible for publishing workflow task events to the Global Inbox, enabling the central application to stay synchronized with task creation, updates, and completion occurring in the source applications.
+2. In the runtime settings of your app, configure the **ASU_GlobalInboxConnector_Startup** microflow for the [after startup property](https://docs.mendix.com/refguide/runtime-tab/#after-startup). If there is already an after startup microflow set, add the **ASU_GlobalInboxConnector_Startup** microflow as an microflow call activity in the existing microflow.
+3. Add the User module roles to the required App roles.
+4. Deploy and configure constants
+    * **AppId**: Must be a unique identifier for each publisher app. Do not change this identifier once configured.
+    * **AppName**: This value will be displayed in your Global Inbox as the publisher app name.
+    * **AppBaseUrl**: Must include the protocol (http:// or https://) and must not end with a trailing slash. It is used as the base URL when redirecting users to the publisher apps.
+5. When a user opens a task from the **Global Inbox**, they are redirected to the corresponding task page in the Publisher Application through a deeplink. Because the user entered the application through the Global Inbox instead of the normal navigation flow, developers must decide how the application should behave when the user completes the user task and/or closes the page. Developers can either change show page action in the deeplink microflow **DL_WorkflowUserTask_ShowUserTaskPage** to redirect to another page or adjust the default deeplink landing page in **UseMe** > **Deeplink** > **Deeplink Landing Page** to meet their business needs. If further customization is rquired, it is possible to adjust the logic for the outcome buttons in each of the task pages.
+
+### Setup Business Events
+
+Configure the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) or [your own Kafka](https://docs.mendix.com/appstore/services/business-events-deployment/#byok) cluster. Refer to the Event Broker documentation for the relevant steps.
+
+### Local Setup
+
+For local development and testing, the Event Broker can be deployed using the [Local Setup Tool](https://github.com/mendix/event-broker-tools) (see [Deployment](https://docs.mendix.com/appstore/services/business-events-deployment/#deployment)). In both the **Global Inbox** and **Global Inbox Connector** modules, configure the following application constants:
+* **ServerUrl**:  the URL of the local broker instance
+* **ChannelName**: the name of the event channel used for publishing and subscribing to Business Events
+
+These settings ensure that Business Events are correctly routed between Publisher Applications and the Global Inbox during local testing.
+
+### Deployment
+
+For deployment, the Global Inbox requires the Mendix Event Broker or an external Kafka cluster. For more information, see [Production Deployment](https://docs.mendix.com/appstore/services/business-events-deployment/#production-deployment) of the Mendix Business Events documentation.
+
+Ensure the Mendix Event Broker is enabled for all apps and environments, and deploy applications in the correct order: Global Inbox application must be running before the publisher applications.
+
+{{% alert color="info" %}}If you are deploying your apps to Mendix Cloud for the first time, you must first stage the application before you can enable the Mendix Event Broker Service in the [Cloud Settings](https://docs.mendix.com/appstore/services/event-broker/#enable-mx-event-broker).{{% /alert %}}
+
+Ensure the **Global Inbox Connector** constants are configured in each Publisher Application as part of the deployment process.
+
+## Security
+
+Any user that can see a task in Publisher Application can see the same task in the **Global Inbox**. This is based on the System.User.Name attribute, that is used as the unique identifier to link users across the applications. For this reason:
+* Single Sign-On (SSO) is required for user authentication
+* Users **must** have the same username (System.User.Name attribute) across the Global Inbox application and all Publisher Applications. 
+* The username should **not** be modifiable and should only be set by the SSO provider.