From 5be54d71eefb0bb2434f57100225e2a60bf48dc5 Mon Sep 17 00:00:00 2001 From: quinntracy Date: Fri, 30 Jan 2026 14:36:39 +0100 Subject: [PATCH 1/4] Split content into relevant docs --- .../services/business-events/_index.md | 40 ++++ .../business-events-configuration.md | 118 ++++++++++ .../business-events-deployment.md} | 211 +----------------- 3 files changed, 162 insertions(+), 207 deletions(-) create mode 100644 content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md create mode 100644 content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md rename content/en/docs/marketplace/platform-supported-content/services/{business-events.md => business-events/business-events-deployment.md} (50%) diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md new file mode 100644 index 00000000000..abafd187b20 --- /dev/null +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md @@ -0,0 +1,40 @@ +--- +title: "Mendix Business Events" +url: /appstore/services/business-events/ +description: "Describes the Mendix Business Events service, which is available in the Mendix Marketplace." +aliases: + - /appstore/modules/business-events/ +#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 + +Business events are like a mailing list to share event notifications between apps. The key difference between business events and traditional communication between apps, like REST or web services, is that there is no direct communication between the different apps. + +With [Mendix Business Events](https://marketplace.mendix.com/link/component/202649), applications can signal when something important happens and can independently subscribe to these events if they want to be informed. + +To deliver these events reliably between your applications, an event broker is required. For apps running Mendix Cloud on licensed nodes, you will need to purchase a license for the [Mendix Event Broker](/appstore/services/event-broker/). + +{{% alert color="info" %}} +Business events are supported in Studio Pro [9.18](/releasenotes/studio-pro/9.18/) and above and currently can only be deployed to the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/).{{% /alert %}} + +### Typical Use Cases + +Business events help you automate the resulting actions when something happens in your organization. They can be useful in a variety of situations, such as: + +* Uploading a payment receipt in one app, while another app processes the outgoing payment in the company's ledger +* Making an appointment with a service provider in an appointment app, then needing it to be added to the scheduling app of the service provider +* Customers placing an order in a web shop, and other apps need to take follow-up actions like scheduling shipments, sending an invoice, and reordering inventory stock + +### Prerequisites + +To use Mendix Business Events, you will need the following: + +* The [Mendix Business Events](https://marketplace.mendix.com/link/component/202649) service from the Mendix Marketplace +* Studio Pro [9.24](/releasenotes/studio-pro/9.24/) and above +* An event broker; this can be a licensed [Mendix Event Broker](#mendix-event-broker) for apps running in Mendix Cloud or the [local testing](#local-testing) broker (see [Deployment](#deployment)) +* [Docker](https://www.docker.com/) for local deployment + +## Licensing {#licensing} + +The Mendix Business Events service itself does not require a license, but it depends on an event broker to deploy to production environments. You can purchase a [Mendix Event Broker License](/appstore/services/event-broker/#event-broker-license) for a broker to be set up for you. See the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) platform service page for more details. You can also run business events on [your own Kafka cluster](#byok). \ No newline at end of file diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md new file mode 100644 index 00000000000..f2bc106c1d3 --- /dev/null +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md @@ -0,0 +1,118 @@ +--- +title: "Business Events Configuration" +url: /appstore/services/business-events/ +description: "Describes the configuration and usage of the Mendix Business Events service." +#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. +--- + +## Configuration + +To work with business events, import the [Mendix Business Events](https://marketplace.mendix.com/link/component/202649) service into your app. See the [Installing Marketplace Content](/appstore/use-content/#install) section in *Using Marketplace Content* for more details. + +### Configuring Local Deployments {#config-local-deployment} + +To test on your development workstation, run the Event Broker on your machine using [Docker](https://www.docker.com/). The required configuration can be found in the [local setup for the event broker tool](https://github.com/mendix/event-broker-tools). + +For local deployment, you need to set the **ChannelName** and **ServerUrl** constants. These constants are best configured by following these steps: + +1. Open the **App Settings**. +2. On the **Configuration** tab, click **New**. +3. Open the **Constants** tab and set the constants as follows: + + * **ChannelName**: `local` + * **ServerUrl**: + * On Windows: `localhost:9092` + * Running Docker on MacOS and Studio Pro on Windows via Parallels: `10.211.55.2:9094` + * Running Docker on Linux and Studio Pro on Windows via VirtualBox/KVM: `:9094` + +### Changing Logging Interval (Optional) + +Optionally, you can set **SummaryLogIntervalSeconds** to a different value. The default value 120, which means if events are consumed or produced, an overview of what was consumed or produced will be logged at `INFO` level every 120 seconds. When configured with 0 or a negative number, this additional logging will not take place at all. + +## Using Business Events {#two-way-be} + +Studio Pro 9.24 and above supports newer behavior of business events, sometimes called two-way business events. In these versions, business events are published by an app and one or more apps consume, or subscribe to, the events. A publisher can also consume a business event of some other publishing app, and a subscriber can publish a business event to another app. + +### Creating a New Business Event Service {#two-way-be-create} + +In your defining app, you can create a new service by doing the following: + +1. Right-click the service folder, hover over **Add other**, then click **Business Event Service**. +2. Select **Create a new business event service**. +3. Enter a **Document name** for the [business event service document](/refguide/business-event-services/) +4. Click **OK**. + +The business event service document is open in Studio Pro: + +{{< figure src="/attachments/appstore/platform-supported-content/services/business-events/new-business-event-service.png" class="no-border" >}} + +### Adding Event Definitions {#add-be-definitions} + +To define what information is included in your events and what the service will implement, click **Add** in the open service document: + +{{< figure src="/attachments/appstore/platform-supported-content/services/business-events/add-event-definition.png" class="no-border" >}} + +1. Define what information is included in this event. + + * In the **General** field, provide the **Event name** and **Description** to let others know what the service is about. + * In the **Attributes** field, click **Add** to define attributes. + * Changes you make here later could lead to breaking changes if the entity the attribute belongs to is consumed. Related entities will be updated automatically. + + {{< figure src="/attachments/appstore/platform-supported-content/services/business-events/wizard-step-1.png" class="no-border" width="400" >}} + +2. Decide what other apps can do and what service this will implement. + + * In the **Other apps can** field, you can select how other apps can use the service. The **This Business Events service implements** field defines whether the service will be responsible for publishing events, subscribing to events, or both. + * Below is an explanation of the possibilities for what other apps can do and what the service implements: + + | If you say that other apps can: | Then the service itself must implement: | The service could also implement: | The following are automatically created: | + | ---------- | ---------- | ---------- | ---------- | + | Publish events | Subscribing to events | Publishing events | **ConsumedBusinessEvent** entity and a [handler microflow](#two-way-be-handler) | + | Subscribe to events | Publishing events | Subscribing to events | When publishing, **PublishedBusinessEvent** entity and handler microflow
If subscribing, a **ConsumedBusinessEvent** entity | + | Publish events and
Subscribe to events | [Nothing required: if apps can do both, there is no obligation for the service to implement anything] | Publishing events and/or subscribing to events | If no service implementations are selected, then nothing created
If publishing, **PublishedBusinessEvent** entity and handler microflow
If subscribing, a **ConsumedBusinessEvent** entity
If both, then both entities and the handler microflow are created| + +3. Click **Done** to exit the wizard and view the defined service document. + + * **Export AsyncAPI Document** exports the YAML file of the business event service so other apps can [use your newly created service](#two-way-be-existing). + +### Attribute Types {#attribute-types} + +Attribute types for business events relate to attribute types of entities, but not all attribute types are supported for business events. The following attribute types are not supported: + +* AutoNumber +* Binary +* Hashed string +* Enumeration (see [Enumeration Attribute Type](#enum-att-type) below) + +In Studio Pro 9.24 and below, all types were supported implicitly because a business event was defined by an entity. The unsupported types were from the perspective of the consumer received as a string. + +#### Enumeration Attribute Type {#enum-att-type} + +In Studio Pro [9.24](/releasenotes/studio-pro/9.24/), consumers see enumerations as a plain string. The names of the enumeration items are the values that are transmitted by the event broker to the subscribers. Enumerations cannot be modeled for new services in Studio Pro [9.24](/releasenotes/studio-pro/9.24/), but for converted earlier apps, the functionality is maintained. + +In Studio Pro [10.0](/releasenotes/studio-pro/10.0/) and above, enumerations are fully supported. The enumeration attribute type can be modeled. The enumeration items are stored in the exported AsyncAPI document, and when imported, a new enumeration document will be created with the name *Enum*. The **Caption** and **Image** fields are not transmitted to the importer of the AsyncAPI document. Captions and images can be provided manually and will not cause conflicts when an AsyncAPI document is re-imported. + +### Using an Existing Business Event Service {#two-way-be-existing} + +To use an existing business service in Studio Pro 9.24 and above, do the following: + +1. Right-click the service folder, hover over **Add other**, then click **Business Event Service**. +2. Select **Use an existing business event service**. +3. Click **Browse** and navigate to the YAML file you exported from the publishing app. +4. Enter a **Document name**, or use the default name, for the [business event service document](/refguide/business-event-services/). +5. Click **OK**. + +### Publishing and Subscribing to Business Events + +After following the instructions in [Using an Existing Business Event Service](#two-way-be-existing), you can publish or subscribe (or both, depending on the [service definitions](#add-be-definitions)) in the following ways: + +* Open the business service document and click **Add** +* Drag and drop the business event from the [Integration pane](/refguide/integration-pane/) to your domain model + +To publish a business event service, you need to use it in a microflow. + +## Automatically Created Event Handler Microflow and Entity {#two-way-be-handler} + +When you click **Add** to add the events from the document into your service, Studio Pro will automatically create a persistable consumed entity within your domain model and an [Event Handler](/refguide/event-handlers/) microflow (**Handle_BE**) to manage the flow of the event after delivery. The **Event Handler** microflow is created in the same directory as your service. + +Currently, Mendix does not support multiple subscribers to the same business event within the same app \ No newline at end of file diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md similarity index 50% rename from content/en/docs/marketplace/platform-supported-content/services/business-events.md rename to content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md index 5f4c9cc6350..3ae60bb967e 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md @@ -1,156 +1,10 @@ --- -title: "Mendix Business Events" -url: /appstore/services/business-events/ -description: "Describes the configuration and usage of the Mendix Business Events service, which is available in the Mendix Marketplace." -aliases: - - /appstore/modules/business-events/ +title: "Deploy as Business Event" +url: /appstore/services/business-events-deployment/ +description: "Describes modeling and deployment of the Mendix Business Events service." #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 - -Business events are like a mailing list to share event notifications between apps. The key difference between business events and traditional communication between apps, like REST or web services, is that there is no direct communication between the different apps. - -With [Mendix Business Events](https://marketplace.mendix.com/link/component/202649), applications can signal when something important happens and can independently subscribe to these events if they want to be informed. - -To deliver these events reliably between your applications, an event broker is required. For apps running Mendix Cloud on licensed nodes, you will need to purchase a license for the [Mendix Event Broker](/appstore/services/event-broker/). - -{{% alert color="info" %}} -Business events are supported in Studio Pro [9.18](/releasenotes/studio-pro/9.18/) and above and currently can only be deployed to the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/).{{% /alert %}} - -### Typical Use Cases - -Business events help you automate the resulting actions when something happens in your organization. They can be useful in a variety of situations, such as: - -* Uploading a payment receipt in one app, while another app processes the outgoing payment in the company's ledger -* Making an appointment with a service provider in an appointment app, then needing it to be added to the scheduling app of the service provider -* Customers placing an order in a web shop, and other apps need to take follow-up actions like scheduling shipments, sending an invoice, and reordering inventory stock - -### Prerequisites - -To use Mendix Business Events, you will need the following: - -* The [Mendix Business Events](https://marketplace.mendix.com/link/component/202649) service from the Mendix Marketplace -* Studio Pro [9.24](/releasenotes/studio-pro/9.24/) and above -* An event broker; this can be a licensed [Mendix Event Broker](#mendix-event-broker) for apps running in Mendix Cloud or the [local testing](#local-testing) broker (see [Deployment](#deployment)) -* [Docker](https://www.docker.com/) for local deployment - -## Licensing {#licensing} - -The Mendix Business Events service itself does not require a license, but it depends on an event broker to deploy to production environments. You can purchase a [Mendix Event Broker License](/appstore/services/event-broker/#event-broker-license) for a broker to be set up for you. See the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) platform service page for more details. You can also run business events on [your own Kafka cluster](#byok). - -## Configuration - -To work with business events, import the [Mendix Business Events](https://marketplace.mendix.com/link/component/202649) service into your app. See the [Installing Marketplace Content](/appstore/use-content/#install) section in *Using Marketplace Content* for more details. - -### Configuring Local Deployments {#config-local-deployment} - -To test on your development workstation, run the Event Broker on your machine using [Docker](https://www.docker.com/). The required configuration can be found in the [local setup for the event broker tool](https://github.com/mendix/event-broker-tools). - -For local deployment, you need to set the **ChannelName** and **ServerUrl** constants. These constants are best configured by following these steps: - -1. Open the **App Settings**. -2. On the **Configuration** tab, click **New**. -3. Open the **Constants** tab and set the constants as follows: - - * **ChannelName**: `local` - * **ServerUrl**: - * On Windows: `localhost:9092` - * Running Docker on MacOS and Studio Pro on Windows via Parallels: `10.211.55.2:9094` - * Running Docker on Linux and Studio Pro on Windows via VirtualBox/KVM: `:9094` - -### Changing Logging Interval (Optional) - -Optionally, you can set **SummaryLogIntervalSeconds** to a different value. The default value 120, which means if events are consumed or produced, an overview of what was consumed or produced will be logged at `INFO` level every 120 seconds. When configured with 0 or a negative number, this additional logging will not take place at all. - -## Using Business Events {#two-way-be} - -Studio Pro 9.24 and above supports newer behavior of business events, sometimes called two-way business events. In these versions, business events are published by an app and one or more apps consume, or subscribe to, the events. A publisher can also consume a business event of some other publishing app, and a subscriber can publish a business event to another app. - -### Creating a New Business Event Service {#two-way-be-create} - -In your defining app, you can create a new service by doing the following: - -1. Right-click the service folder, hover over **Add other**, then click **Business Event Service**. -2. Select **Create a new business event service**. -3. Enter a **Document name** for the [business event service document](/refguide/business-event-services/) -4. Click **OK**. - -The business event service document is open in Studio Pro: - -{{< figure src="/attachments/appstore/platform-supported-content/services/business-events/new-business-event-service.png" class="no-border" >}} - -### Adding Event Definitions {#add-be-definitions} - -To define what information is included in your events and what the service will implement, click **Add** in the open service document: - -{{< figure src="/attachments/appstore/platform-supported-content/services/business-events/add-event-definition.png" class="no-border" >}} - -1. Define what information is included in this event. - - * In the **General** field, provide the **Event name** and **Description** to let others know what the service is about. - * In the **Attributes** field, click **Add** to define attributes. - * Changes you make here later could lead to breaking changes if the entity the attribute belongs to is consumed. Related entities will be updated automatically. - - {{< figure src="/attachments/appstore/platform-supported-content/services/business-events/wizard-step-1.png" class="no-border" width="400" >}} - -2. Decide what other apps can do and what service this will implement. - - * In the **Other apps can** field, you can select how other apps can use the service. The **This Business Events service implements** field defines whether the service will be responsible for publishing events, subscribing to events, or both. - * Below is an explanation of the possibilities for what other apps can do and what the service implements: - - | If you say that other apps can: | Then the service itself must implement: | The service could also implement: | The following are automatically created: | - | ---------- | ---------- | ---------- | ---------- | - | Publish events | Subscribing to events | Publishing events | **ConsumedBusinessEvent** entity and a [handler microflow](#two-way-be-handler) | - | Subscribe to events | Publishing events | Subscribing to events | When publishing, **PublishedBusinessEvent** entity and handler microflow
If subscribing, a **ConsumedBusinessEvent** entity | - | Publish events and
Subscribe to events | [Nothing required: if apps can do both, there is no obligation for the service to implement anything] | Publishing events and/or subscribing to events | If no service implementations are selected, then nothing created
If publishing, **PublishedBusinessEvent** entity and handler microflow
If subscribing, a **ConsumedBusinessEvent** entity
If both, then both entities and the handler microflow are created| - -3. Click **Done** to exit the wizard and view the defined service document. - - * **Export AsyncAPI Document** exports the YAML file of the business event service so other apps can [use your newly created service](#two-way-be-existing). - -### Attribute Types {#attribute-types} - -Attribute types for business events relate to attribute types of entities, but not all attribute types are supported for business events. The following attribute types are not supported: - -* AutoNumber -* Binary -* Hashed string -* Enumeration (see [Enumeration Attribute Type](#enum-att-type) below) - -In Studio Pro 9.24 and below, all types were supported implicitly because a business event was defined by an entity. The unsupported types were from the perspective of the consumer received as a string. - -#### Enumeration Attribute Type {#enum-att-type} - -In Studio Pro [9.24](/releasenotes/studio-pro/9.24/), consumers see enumerations as a plain string. The names of the enumeration items are the values that are transmitted by the event broker to the subscribers. Enumerations cannot be modeled for new services in Studio Pro [9.24](/releasenotes/studio-pro/9.24/), but for converted earlier apps, the functionality is maintained. - -In Studio Pro [10.0](/releasenotes/studio-pro/10.0/) and above, enumerations are fully supported. The enumeration attribute type can be modeled. The enumeration items are stored in the exported AsyncAPI document, and when imported, a new enumeration document will be created with the name *Enum*. The **Caption** and **Image** fields are not transmitted to the importer of the AsyncAPI document. Captions and images can be provided manually and will not cause conflicts when an AsyncAPI document is re-imported. - -### Using an Existing Business Event Service {#two-way-be-existing} - -To use an existing business service in Studio Pro 9.24 and above, do the following: - -1. Right-click the service folder, hover over **Add other**, then click **Business Event Service**. -2. Select **Use an existing business event service**. -3. Click **Browse** and navigate to the YAML file you exported from the publishing app. -4. Enter a **Document name**, or use the default name, for the [business event service document](/refguide/business-event-services/). -5. Click **OK**. - -### Publishing and Subscribing to Business Events - -After following the instructions in [Using an Existing Business Event Service](#two-way-be-existing), you can publish or subscribe (or both, depending on the [service definitions](#add-be-definitions)) in the following ways: - -* Open the business service document and click **Add** -* Drag and drop the business event from the [Integration pane](/refguide/integration-pane/) to your domain model - -To publish a business event service, you need to use it in a microflow. - -## Automatically Created Event Handler Microflow and Entity {#two-way-be-handler} - -When you click **Add** to add the events from the document into your service, Studio Pro will automatically create a persistable consumed entity within your domain model and an [Event Handler](/refguide/event-handlers/) microflow (**Handle_BE**) to manage the flow of the event after delivery. The **Event Handler** microflow is created in the same directory as your service. - -Currently, Mendix does not support multiple subscribers to the same business event within the same app. - ## Modeling with Business Events (All Supported Studio Pro Versions) {#be-modelling} Once you have created a service in [Studio Pro 9.24 and above](#two-way-be), you can start modeling with them in your app. @@ -342,61 +196,4 @@ Below is an example of a Postgres service that you can add to your `docker-compo PGPASSWORD: mendix ports: - "25432:5432" -``` - -## Frequently Asked Questions - -1. Can I undo a Publish Event action in case my microflow fails? - - Yes. If you do a rollback in an error handler, the business event will not be sent to other applications. - -2. Can I publish my own events from other software directly to a Kafka topic? - - No, that is currently not supported when using Mendix Cloud Event Broker. This can be achieved on [your own Kafka cluster](#byok). - -3. Can I send related or associated objects as a single business event? - - No, only a flat object. For complex data structures, provide an API where the consuming app can retrieve the complex structure upon retrieval of a business event. Alternatively, you can use a string attribute in the business event to store JSON or XML using mappings. - -4. I want to replicate data between my Mendix apps. Should I use business events? - - Business events can help you replicate data more efficiently by ensuring you do not have to poll continuously. To share data, it is still preferable to use OData or REST. - -5. Are business events guaranteed to be delivered only once? - - The [Outbox](#be-entities) will publish each business event only once. This does not prevent business logic from sending duplicate messages to the Outbox. - -6. Are business events guaranteed to be delivered in the original sequence? - - Events are delivered in the sequence they are produced. The Mendix Business Events service, however, persists the event to the **Entity** table in this order. Once the entity is persisted, it triggers the microflow for the persisted entity. A failure in the microflow can cause data to become out of sequence. Event ordering is not currently a feature of the Mendix Business Event service. - -7. How do I detect and correct failed processing of received events? - - The Mendix Business Events service uses [Task Queue](/refguide/task-queue/) to publish and consume events, so all the capabilities of observability of task queue can be used here as well. - -8. How do I configure which Kafka cluster to use? - - During modeling, you can use the **Constants** described in the [Configuring Local Deployments](#config-local-deployment) section to configure to a local or other Kafka. This does not transfer through to runtime. - -9. How do I delete or clean up events and tasks? - - This will be implemented in a forthcoming release. In the meantime, you could use scheduled event to clean up the events yourself (make sure the consumer doesn’t need them anymore). For the task queue, the **Task Queue Helpers**, a service linked in [Task Queue](/refguide/task-queue/), can be used. - -10. How do I know the event was successfully published? - - Messages are first queued within the **Outbox** for successful delivery as a business event, after which they are deleted. You can match the unique `Event Id` to your business event. Monitoring the **Outbox** entity will allow the developer to determine if there are unpublished business event entities. See the [Business Event Entities](#be-entities) for more information on the **Outbox**. - -11. How do I know events are consumed successfully? - - The flow of events are controlled by the persistence of the event to the **Consumed Business Event** entity (see [Business Event Entities](#be-entities)). The flow will not continue in the case of such a failure. They only cause for such failure would be database-related and is unlikely to occur. - - On the microflow, a log message action can be added after the start action in order to track the movement. Refer to the [Dead Letter Queue for Failed Messages](#dead-letter-queue) section for more information. - -## Read More - -Check out the following release blogs for more information about business events: - -* [Mendix Studio Pro 9.18 release blog](https://www.mendix.com/blog/mendix-release-9-18-next-level-performance/) -* [Mendix Studio Pro 9.24 release blog](https://www.mendix.com/blog/mendix-release-9-24-what-a-ride-it-has-been/) - -For more information about the business event service documents, see [Business Event Services](/refguide/business-event-services/) in the *Studio Pro Guide*. +``` \ No newline at end of file From ee01d3c03d83ef679c3bd6baff7ac79310de9b61 Mon Sep 17 00:00:00 2001 From: quinntracy Date: Fri, 30 Jan 2026 14:51:26 +0100 Subject: [PATCH 2/4] Update intros and read more sections --- .../services/business-events/_index.md | 9 ++++++++- .../business-events-configuration.md | 13 ++++++++++--- .../business-events/business-events-deployment.md | 7 ++++++- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md index abafd187b20..d1e0dce4a79 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md @@ -37,4 +37,11 @@ To use Mendix Business Events, you will need the following: ## Licensing {#licensing} -The Mendix Business Events service itself does not require a license, but it depends on an event broker to deploy to production environments. You can purchase a [Mendix Event Broker License](/appstore/services/event-broker/#event-broker-license) for a broker to be set up for you. See the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) platform service page for more details. You can also run business events on [your own Kafka cluster](#byok). \ No newline at end of file +The Mendix Business Events service itself does not require a license, but it depends on an event broker to deploy to production environments. You can purchase a [Mendix Event Broker License](/appstore/services/event-broker/#event-broker-license) for a broker to be set up for you. See the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) platform service page for more details. You can also run business events on [your own Kafka cluster](#byok). + +## Read More + +Read more to learn how to configure and deploy business events in the following documents: + +* [Business Event Configuration](/appstore/services/business-events-configuration/) +* [Deploy a Business Event](/appstore/services/business-events-deployment/) \ No newline at end of file diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md index f2bc106c1d3..84453b109dc 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-configuration.md @@ -1,14 +1,16 @@ --- title: "Business Events Configuration" -url: /appstore/services/business-events/ +url: /appstore/services/business-events-configuration/ description: "Describes the configuration and usage of the Mendix Business Events service." #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. --- -## Configuration +## Introduction To work with business events, import the [Mendix Business Events](https://marketplace.mendix.com/link/component/202649) service into your app. See the [Installing Marketplace Content](/appstore/use-content/#install) section in *Using Marketplace Content* for more details. +## Configuration + ### Configuring Local Deployments {#config-local-deployment} To test on your development workstation, run the Event Broker on your machine using [Docker](https://www.docker.com/). The required configuration can be found in the [local setup for the event broker tool](https://github.com/mendix/event-broker-tools). @@ -115,4 +117,9 @@ To publish a business event service, you need to use it in a microflow. When you click **Add** to add the events from the document into your service, Studio Pro will automatically create a persistable consumed entity within your domain model and an [Event Handler](/refguide/event-handlers/) microflow (**Handle_BE**) to manage the flow of the event after delivery. The **Event Handler** microflow is created in the same directory as your service. -Currently, Mendix does not support multiple subscribers to the same business event within the same app \ No newline at end of file +Currently, Mendix does not support multiple subscribers to the same business event within the same app. + +## Read More + +* [Deploy a Business Event](/appstore/services/business-events-deployment/) +* [Mendix Event Broker](/appstore/services/event-broker/) \ No newline at end of file diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md index 3ae60bb967e..1423cc71c02 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md @@ -196,4 +196,9 @@ Below is an example of a Postgres service that you can add to your `docker-compo PGPASSWORD: mendix ports: - "25432:5432" -``` \ No newline at end of file +``` + +## Read More + +* [Business Event Configuration](/appstore/services/business-events-configuration/) +* [Mendix Event Broker](/appstore/services/event-broker/) \ No newline at end of file From 05697a2efddb7ead3e8d6492fc66ee0872d9e77e Mon Sep 17 00:00:00 2001 From: quinntracy Date: Fri, 30 Jan 2026 14:55:29 +0100 Subject: [PATCH 3/4] Typo --- .../services/business-events/business-events-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md index 1423cc71c02..61aa0eb77b2 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md @@ -1,5 +1,5 @@ --- -title: "Deploy as Business Event" +title: "Deploy a Business Event" url: /appstore/services/business-events-deployment/ description: "Describes modeling and deployment of the Mendix Business Events service." #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. From c21b1935d00ba9ff4ffc0271d14da497b31d4b00 Mon Sep 17 00:00:00 2001 From: quinntracy Date: Mon, 2 Feb 2026 11:19:37 +0100 Subject: [PATCH 4/4] FAQs and links --- .../services/business-events/_index.md | 52 ++++++++++++++++++- .../business-events-deployment.md | 6 ++- 2 files changed, 54 insertions(+), 4 deletions(-) diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md index d1e0dce4a79..79f29297c39 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md @@ -18,7 +18,7 @@ To deliver these events reliably between your applications, an event broker is r {{% alert color="info" %}} Business events are supported in Studio Pro [9.18](/releasenotes/studio-pro/9.18/) and above and currently can only be deployed to the [Mendix Cloud](/developerportal/deploy/mendix-cloud-deploy/).{{% /alert %}} -### Typical Use Cases +## Typical Use Cases Business events help you automate the resulting actions when something happens in your organization. They can be useful in a variety of situations, such as: @@ -26,7 +26,7 @@ Business events help you automate the resulting actions when something happens i * Making an appointment with a service provider in an appointment app, then needing it to be added to the scheduling app of the service provider * Customers placing an order in a web shop, and other apps need to take follow-up actions like scheduling shipments, sending an invoice, and reordering inventory stock -### Prerequisites +## Prerequisites To use Mendix Business Events, you will need the following: @@ -39,6 +39,54 @@ To use Mendix Business Events, you will need the following: The Mendix Business Events service itself does not require a license, but it depends on an event broker to deploy to production environments. You can purchase a [Mendix Event Broker License](/appstore/services/event-broker/#event-broker-license) for a broker to be set up for you. See the [Mendix Event Broker](https://marketplace.mendix.com/link/component/202907) platform service page for more details. You can also run business events on [your own Kafka cluster](#byok). +## Frequently Asked Questions + +1. Can I undo a Publish Event action in case my microflow fails? + + Yes. If you do a rollback in an error handler, the business event will not be sent to other applications. + +2. Can I publish my own events from other software directly to a Kafka topic? + + No, that is currently not supported when using Mendix Cloud Event Broker. This can be achieved on [your own Kafka cluster](#byok). + +3. Can I send related or associated objects as a single business event? + + No, only a flat object. For complex data structures, provide an API where the consuming app can retrieve the complex structure upon retrieval of a business event. Alternatively, you can use a string attribute in the business event to store JSON or XML using mappings. + +4. I want to replicate data between my Mendix apps. Should I use business events? + + Business events can help you replicate data more efficiently by ensuring you do not have to poll continuously. To share data, it is still preferable to use OData or REST. + +5. Are business events guaranteed to be delivered only once? + + The [Outbox](#be-entities) will publish each business event only once. This does not prevent business logic from sending duplicate messages to the Outbox. + +6. Are business events guaranteed to be delivered in the original sequence? + + Events are delivered in the sequence they are produced. The Mendix Business Events service, however, persists the event to the **Entity** table in this order. Once the entity is persisted, it triggers the microflow for the persisted entity. A failure in the microflow can cause data to become out of sequence. Event ordering is not currently a feature of the Mendix Business Event service. + +7. How do I detect and correct failed processing of received events? + + The Mendix Business Events service uses [Task Queue](/refguide/task-queue/) to publish and consume events, so all the capabilities of observability of task queue can be used here as well. + +8. How do I configure which Kafka cluster to use? + + During modeling, you can use the **Constants** described in the [Configuring Local Deployments](#config-local-deployment) section to configure to a local or other Kafka. This does not transfer through to runtime. + +9. How do I delete or clean up events and tasks? + + This will be implemented in a forthcoming release. In the meantime, you could use scheduled event to clean up the events yourself (make sure the consumer doesn’t need them anymore). For the task queue, the **Task Queue Helpers**, a service linked in [Task Queue](/refguide/task-queue/), can be used. + +10. How do I know the event was successfully published? + + Messages are first queued within the **Outbox** for successful delivery as a business event, after which they are deleted. You can match the unique `Event Id` to your business event. Monitoring the **Outbox** entity will allow the developer to determine if there are unpublished business event entities. See the [Business Event Entities](#be-entities) for more information on the **Outbox**. + +11. How do I know events are consumed successfully? + + The flow of events are controlled by the persistence of the event to the **Consumed Business Event** entity (see [Business Event Entities](#be-entities)). The flow will not continue in the case of such a failure. They only cause for such failure would be database-related and is unlikely to occur. + + On the microflow, a log message action can be added after the start action in order to track the movement. Refer to the [Dead Letter Queue for Failed Messages](#dead-letter-queue) section for more information. + ## Read More Read more to learn how to configure and deploy business events in the following documents: diff --git a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md index 61aa0eb77b2..5f4707cf2a6 100644 --- a/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md +++ b/content/en/docs/marketplace/platform-supported-content/services/business-events/business-events-deployment.md @@ -5,9 +5,11 @@ description: "Describes modeling and deployment of the Mendix Business Events se #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. --- -## Modeling with Business Events (All Supported Studio Pro Versions) {#be-modelling} +## Introduction + +Once you have created a service in [Studio Pro 9.24 and above](/appstore/services/business-events-configuration/#two-way-be), you can start modeling with them in your app and deploy your Business Event. -Once you have created a service in [Studio Pro 9.24 and above](#two-way-be), you can start modeling with them in your app. +## Modeling with Business Events (All Supported Studio Pro Versions) {#be-modelling} Business events are defined using entities specializing the **PublishedBusinessEvent** entity that is included in the Mendix Business Events service.