Merge pull request mendix#10688 from mendix/qt-businessevents

Too long to translate: Business Events

Author: quinntracy

content/en/docs/developerportal/digital-execution/implement-mendix/launch-app.md

@@ -58,7 +58,7 @@ Things you can customize for your apps in Mendix Cloud include:
 * [HTTP headers](/howto/security/best-practices-security/#adding-http-header)
 * [Path-based access restrictions](/developerportal/deploy/access-restrictions/)
 * [Environment variables](/developerportal/deploy/environments-details/#custom-environment-variables)
-* [Services](/developerportal/deploy/environments-details/#services), such as [the Event Broker service](/appstore/services/business-events/#mendix-event-broker)
+* [Services](/developerportal/deploy/environments-details/#services), such as [the Event Broker service](/appstore/services/event-broker/)
 
 #### Deploying the App
 

content/en/docs/marketplace/platform-supported-content/services/business-events.md

@@ -0,0 +1,95 @@
+---
+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](/appstore/services/event-broker/) for apps running in Mendix Cloud or the [local testing](/appstore/services/business-events-deployment/#local-testing) broker (see [Deployment](/appstore/services/business-events-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](/appstore/services/business-events-deployment/#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](/appstore/services/business-events-deployment/#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](/appstore/services/business-events-deployment/#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](/appstore/services/business-events-configuration/#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](/appstore/services/business-events-deployment/#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](/appstore/services/business-events-deployment/#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](/appstore/services/business-events-deployment/#dead-letter-queue) section for more information.
+
+## 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/)

content/en/docs/marketplace/platform-supported-content/services/business-events/_index.md

@@ -0,0 +1,125 @@
+---
+title: "Business Events Configuration"
+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.
+---
+
+## 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).
+
+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: `<IP ADDRESS>: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/business-events-config/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/business-events-config/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/business-events-config/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 <br>If subscribing, a **ConsumedBusinessEvent** entity |
+    | Publish events and<br>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 <br>If publishing, **PublishedBusinessEvent** entity and handler microflow <br>If subscribing, a **ConsumedBusinessEvent** entity <br>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 *<attributeName>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.
+
+## Read More
+
+* [Deploy a Business Event](/appstore/services/business-events-deployment/)
+* [Mendix Event Broker](/appstore/services/event-broker/)