diff --git a/docs/components/camunda-integrations/sap/eventing.md b/docs/components/camunda-integrations/sap/eventing.md index fe315ebb8d3..13a162f4c91 100644 --- a/docs/components/camunda-integrations/sap/eventing.md +++ b/docs/components/camunda-integrations/sap/eventing.md @@ -1,130 +1,125 @@ --- id: eventing -title: SAP Eventing with SAP Advanced Event Mesh (AEM) -description: "React on CloudEvents to/from Advanced Event Mesh in a BPMN process" +title: SAP eventing with SAP Advanced Event Mesh (AEM) +description: React to CloudEvents between Camunda and SAP Advanced Event Mesh (AEM) in a BPMN process. sidebar_label: SAP Eventing --- Receive [CloudEvents](https://cloudevents.io/) from SAP Advanced Event Mesh (AEM) and send CloudEvents to AEM. -## About SAP Eventing +## About SAP eventing -This consists of three connectors that allow bidirectional communication between Camunda and AEM. +SAP eventing uses three connectors that enable bidirectional communication between Camunda and AEM. -| Connector | Description | -| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SAP Eventing Outbound Connector | Send CloudEvents from Camunda to an AEM topic or queue endpoint. | -| SAP Eventing Message Start Event Connector | Translate an incoming CloudEvent from AEM into a [BPMN Message Start Event](/components/modeler/bpmn/message-events/message-events.md#message-start-events) triggering a new process instance. | -| SAP Eventing Intermediate Event Connector | Translate an incoming CloudEvent from AEM into a [BPMN Intermediate Catch Event](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events) allowing an active process to continue based on the event. | +| Connector | Description | +| :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SAP Eventing Outbound Connector | Sends CloudEvents from Camunda to an AEM topic or queue endpoint. | +| SAP Eventing Message Start Event Connector | Translates an incoming CloudEvent from AEM into a [BPMN Message Start Event](/components/modeler/bpmn/message-events/message-events.md#message-start-events) to trigger a new process instance. | +| SAP Eventing Intermediate Event Connector | Translates an incoming CloudEvent from AEM into a [BPMN Intermediate Catch Event](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events) to allow an active process to continue based on the event. | -The integration uses `HTTP` as the transport protocol. +The integration uses **HTTP** as the transport protocol: -- The incoming connectors act as webhooks, receiving CloudEvent payloads and delivering them into process instances. -- The outbound connector sends `HTTP POST` requests to an Advanced Event Mesh [topic](https://docs.solace.com/Messaging/Guaranteed-Msg/Topic-Endpoints.htm) or [queue](https://docs.solace.com/Messaging/Guaranteed-Msg/Queues.htm) endpoints. +- Incoming connectors act as webhooks, receiving CloudEvent payloads and delivering them into process instances. +- The outbound connector sends `HTTP POST` requests to an AEM [topic](https://docs.solace.com/Messaging/Guaranteed-Msg/Topic-Endpoints.htm) or [queue](https://docs.solace.com/Messaging/Guaranteed-Msg/Queues.htm) endpoint. :::info -SAP Advanced Event Mesh uses [Solace Event Broker](https://solace.com/products/event-broker/) as its core event broker. -This means the terms **AEM** and **Solace Event Broker** can be used interchangeably when referring to core eventing functionality. +SAP Advanced Event Mesh uses [Solace Event Broker](https://solace.com/products/event-broker/) as its core event broker. +The terms **AEM** and **Solace Event Broker** can be used interchangeably when referring to eventing functionality. ::: ## Prerequisites -As `HTTP` is used as the transport protocol, AEM must be configured to use [REST messaging](https://docs.solace.com/API/REST/REST-get-start.htm). -This enables publishers and subscribers to communicate over HTTP. +Because **HTTP** is used as the transport protocol, AEM must be configured to use [REST messaging](https://docs.solace.com/API/REST/REST-get-start.htm). This enables publishers and subscribers to communicate over HTTP. -The following configuration examples in Camunda build on the Solace tutorial [Publish/Subscribe REST Messaging](https://tutorials.solace.dev/rest-messaging/publish-subscribe/), which provides detailed steps for setting up REST-based publish/subscribe messaging. +The configuration examples below build on the Solace tutorial [Publish/Subscribe REST Messaging](https://tutorials.solace.dev/rest-messaging/publish-subscribe/), which provides detailed steps for setting up REST-based publish/subscribe messaging. ## Installation -You can install the SAP Eventing connectors directly from the [Camunda Marketplace](https://marketplace.camunda.com/). +Install the SAP Eventing connectors directly from the [Camunda Marketplace](https://marketplace.camunda.com/). -## Configuration +## Configuration overview - [SAP Eventing Message Start Event Connector](#sap-eventing-message-start-event-connector) - [SAP Eventing Intermediate Event Connector](#sap-eventing-intermediate-event-connector) +- [SAP Eventing Outbound Connector](#sap-eventing-outbound-connector) ## SAP Eventing Message Start Event Connector -Inbound CloudEvents → BPMN Message +Inbound CloudEvents → BPMN message. -Applying the **SAP Eventing Message Start Event Connector** generates a unique **Webhook URL** that starts a new BPMN process instance when invoked. +Applying the **SAP Eventing Message Start Event Connector** generates a unique **webhook URL** that starts a new BPMN process instance when invoked. -![webhook URL ](./img/eventing-webhook.png) +![Webhook URL](./img/eventing-webhook.png) :::info -The Webhook URL is generated **only after the initial deployment** of the process. +The webhook URL is generated **only after the initial deployment** of the process. ::: -This Webhook URL must be registered as a target in **SAP Advanced Event Mesh (AEM)**. - +This URL must be registered as a target in **SAP Advanced Event Mesh (AEM)**. The host portion of the URL (`https://.connectors.camunda.io`) is used when configuring the **REST consumer** in AEM. ![AEM REST consumer](./img/eventing-aem-rest-consumer.png) ### Authentication -In the same REST consumer configuration, set up authentication from AEM to the Camunda Webhook endpoint. - -The credentials configured in the **Authorization** section of the Camunda connector must correspond to the **Authentication Scheme** used in AEM. +In the REST consumer configuration, set up authentication from AEM to the Camunda webhook endpoint. +The credentials configured in the **Authorization** section of the Camunda connector must match the **authentication scheme** used in AEM. ![Camunda and AEM credentials](./img/eventing-authorization.png) -### Queue Binding +### Queue binding -The path component of the Camunda Webhook URL must be used as the **POST Request Target** in the **Queue Binding** of the REST consumer. +The path component of the Camunda webhook URL must be used as the **POST request target** in the **Queue Binding** of the REST consumer. ![AEM Queue Binding](./img/eventing-aem-queue-binding.png) -### Other Configuration Options +### Other configuration options -The remaining configuration options of the **SAP Eventing Message Start Event Connector** match those of the [HTTP Webhook Connector](/components/connectors/protocol/http-webhook.md), except for one key difference: +The remaining configuration options are identical to those of the [HTTP Webhook Connector](/components/connectors/protocol/http-webhook.md), except for one key difference: -> The default **Webhook response** explicitly returns a `200` status code and an `"OK"` message body, confirming that the CloudEvent was successfully received and acknowledged by Camunda. +> The default webhook response explicitly returns a `200` status code and an `"OK"` message body, confirming that the CloudEvent was successfully received and acknowledged by Camunda. ![Remaining Incoming Webhook config](./img/eventing-incoming-other-config.png) -### Event Flow +### Event flow -When a CloudEvent is received from AEM, all **header** properties and the **body** payload are relayed as-is to the target process instance, either: +When a CloudEvent is received from AEM, all **header properties** and the **body payload** are relayed to the target process instance, either: -- At process creation, when using the **SAP Eventing Message Start Event Connector**, or -- During event correlation, when using the **SAP Eventing Intermediate Event Connector**. +- At process creation (Message Start Event), or +- During event correlation (Intermediate Event). This ensures that message attributes and payload data from AEM are preserved end-to-end within the Camunda process. ## SAP Eventing Intermediate Event Connector -### Correlate CloudEvents as BPMN Messages - -The **SAP Eventing Intermediate Event Connector** injects a CloudEvent from **SAP Advanced Event Mesh (AEM)** into an _active_ Camunda BPMN process instance. +### Correlate CloudEvents as BPMN messages -It does this by leveraging the BPMN principle of [**message correlation**](/components/connectors/protocol/http-webhook.md#correlation). +The **SAP Eventing Intermediate Event Connector** injects a CloudEvent from AEM into an active Camunda process instance using [message correlation](/components/connectors/protocol/http-webhook.md#correlation). -Any CloudEvent property can be used as a **correlation key** to map incoming event data to the correct process instance. +Any CloudEvent property can be used as a **correlation key** to match incoming event data to the correct process instance. -### Correlation via CloudEvent Body +### Correlation via CloudEvent body -The configuration options of the **SAP Eventing Message Start Event Connector** and the **SAP Eventing Intermediate Event Connector** are identical, except that the _Intermediate Event_ requires an additional **Correlation** section to be configured. +The configuration options of the **Message Start** and **Intermediate Event** connectors are identical, except that the intermediate event requires an additional **Correlation** section. ![Intermediate Message Correlation](./img/eventing-intermediate-correlation.png) -- In the example above, the process variable `ENCOMGridID` is expected to exist within the process instance. +- In the example above, the process variable `ENCOMGridID` must exist within the process instance. - Its value is compared against the CloudEvent payload (`request.body.FlynnLocationID`). -- If both values match, the CloudEvent is considered to be the published BPMN message that is correlated to the corresponding process instance. +- If both values match, the CloudEvent is correlated to that process instance. -### Correlation via CloudEvent Metadata +### Correlation via CloudEvent metadata Since **HTTP** is used as the transport protocol, the [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) requires all CloudEvent metadata to be passed as **HTTP headers**. -In addition, AEM prepends all user properties with the prefix `Solace-User-Property-` to persist them in its event engine. For example, a CloudEvent with the property `"ce-id"` is represented in AEM as the HTTP header named `Solace-User-Property-ce-id` +AEM prepends all user properties with the prefix `Solace-User-Property-`. +For example, the CloudEvent property `ce-id` is represented as the HTTP header `Solace-User-Property-ce-id`. -This means that to perform BPMN message correlation based on CloudEvent metadata, reference the corresponding **HTTP header name** including the `Solace-User-Property-` prefix. +To correlate on metadata, reference the header name including this prefix. -#### Example: CloudEvent HTTP Message - -The following is an example of a CloudEvent HTTP request received by Camunda: +#### Example: CloudEvent HTTP message ```json { @@ -132,70 +127,55 @@ The following is an example of a CloudEvent HTTP request received by Camunda: "body": { "FlynnLocationID": "34.0522,-118.2437" }, "headers": { "host": ".connectors.camunda.io", - "x-request-id": "956de0835ad61a211a20e4755315b413e", - "x-real-ip": "12.123.123.456", - "x-forwarded-host": ".connectors.camunda.io", - "x-forwarded-port": "443", - "x-forwarded-proto": "https", - "x-forwarded-scheme": "https", - "x-scheme": "https", - "content-length": "44", "authorization": "Basic CaMUnDakZW1v", - "cache-control": "no-cache", "content-type": "application/json", - "solace-delivery-mode": "Persistent", "solace-user-property-ce-specversion": "1.0", "solace-user-property-ce-type": "sap.s4.beh.encom.grid.program.v1", "solace-user-property-ce-source": "/alan/pager/buzz", "solace-user-property-ce-subject": "CLU-2.0", "solace-user-property-ce-id": "Argon-T-01", "solace-user-property-ce-time": "2018-04-05T03:56:24Z", - "solace-user-property-ce-datacontenttype": "application/json", - "user-agent": "Solace_PubSub+_Enterprise/10.11.1.167" - }, - "params": {} - }, - "connectorData": {}, - "documents": [] + "solace-user-property-ce-datacontenttype": "application/json" + } + } } ``` -In this example, to correlate the CloudEvent `ce-id` property to a process instance, reference it as: -`` request.headers.`solace-user-property-ce-id` `` in the header field. +To correlate on the `ce-id` property, use `request.headers.solace-user-property-ce-id`. ![Mapping to CloudEvent meta data](./img/eventing-correlation-ce-headers.png) :::tip -Note the "backticks" notation of the header value `` request.headers.`solace-user-property-ce-id` `` to escape the dashes in the header field name. +Use backticks to escape dashes in the header name, for example: +`` request.headers.`solace-user-property-ce-id` ``. ::: -### SAP Eventing Outbound Connector +## SAP Eventing Outbound Connector -The **SAP Eventing Outbound Connector** allows you to send CloudEvents to **SAP Advanced Event Mesh (AEM)** using its **REST messaging** capability. It uses the REST messaging capability of AEM to publish the CloudEvent via a `HTTP POST` request. +The **SAP Eventing Outbound Connector** allows you to send CloudEvents to AEM using its REST messaging capability. It publishes the event using an `HTTP POST` request. ![SAP eventing outbound connector configuration](./img/eventing-outbound-connector.png) ### Endpoint -The **Endpoint** field specifies the URL of your AEM Event Broker. +The **Endpoint** field specifies the URL of your AEM event broker. -You can find this URL in the Advanced Event Mesh's web interface by navigating to: +You can find this URL in AEM’s web interface: > **Cluster Manager → Your Cluster → (Service Details) → Connect → Connect with Java → Solace REST Messaging API** -On the right-hand side of the interface is the **FQDN** (Fully Qualified Domain Name) of your AEM broker instance. +The **FQDN** (fully qualified domain name) is shown on the right-hand side. ![FQDN of the AEM REST messaging API](./img/eventing-aem-rest-fqdn.png) -### Topic / Queue - -Specify the target **topic** or **queue** path where the CloudEvent will be published. +### Topic / queue -Neither value should begin with a `/` — the connector includes a validation check to prevent this. +Specify the target **topic** or **queue** path where the CloudEvent will be published. +Do not begin the path with `/` — the connector includes a validation check to prevent this. ### Authorization -Select one of the following authorization methods: +Supported authorization methods: - `None` - `API Key` @@ -205,13 +185,14 @@ Select one of the following authorization methods: ### CloudEvent -While CloudEvent metadata (for example, `ce-id` or `ce-subject`) is automatically handled by the AEM broker—including the required `Solace-User-Property-` prefix, you only need to configure the **standard CloudEvent attributes** in this connector. +CloudEvent metadata (e.g., `ce-id`, `ce-subject`) is automatically handled by the AEM broker, including the required `Solace-User-Property-` prefix. +Configure only the standard CloudEvent attributes in the connector. -The CloudEvent data is serialized into a **JSON body**, and both the **metadata** and **data** fields support [FEEL expressions](/components/modeler/feel/what-is-feel.md) for dynamic values. +The CloudEvent data is serialized into a **JSON body**, and both metadata and data fields support [FEEL expressions](/components/modeler/feel/what-is-feel.md) for dynamic values. ![Eventing Outbound CloudEvent](./img/eventing-outbound-cloudevent.png) -### Other Configuration Options +### Other configuration options All remaining options are identical to those of the [REST Connector](/components/connectors/protocol/rest.md), including: diff --git a/docs/components/camunda-integrations/sap/prerequisites.md b/docs/components/camunda-integrations/sap/prerequisites.md index acd1c73cdfb..cdbfc518c1a 100644 --- a/docs/components/camunda-integrations/sap/prerequisites.md +++ b/docs/components/camunda-integrations/sap/prerequisites.md @@ -1,49 +1,48 @@ --- id: prerequisites title: Prerequisites -description: "Checklist of Camunda, SAP, authentication, and connectivity requirements before deploying the SAP integration modules." +description: "Review the required Camunda components, SAP services, authentication setup, and connectivity before deploying the SAP integration modules." --- -Before setting up the SAP integration, ensure that the following requirements are met. +Before setting up the SAP integration, ensure the following requirements are met. ## Camunda setup -- **OData and RFC Connectors:** 8.6+ +- **OData and RFC connectors:** 8.6+ - **BTP Plugin:** 8.6+ -- **Advanced Event Mesh Integration:** 8.6+ +- **Advanced Event Mesh integration:** 8.6+ -Works with both **SaaS** and **Self-Managed** deployments: +Compatible with both **SaaS** and **Self-Managed** deployments: -- **SaaS:** Configure [hybrid connectors](/components/connectors/use-connectors-in-hybrid-mode.md) to securely connect to SAP systems. -- **Self-Managed:** Ensure outbound connectivity from your environment to SAP BTP. +- **SaaS:** Use [hybrid connectors](/components/connectors/use-connectors-in-hybrid-mode.md) to securely connect to SAP systems. +- **Self-Managed:** Ensure outbound network connectivity from your environment to SAP BTP. ## SAP setup -You’ll need an **SAP BTP subaccount** with the following services enabled: +You need an **SAP BTP subaccount** with these services enabled: - [**Cloud Foundry Runtime**](https://discovery-center.cloud.sap/serviceCatalog/cloud-foundry-runtime?region=all) -- [**Destination Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/destination?region=all&service_plan=lite&commercialModel=btpea) - for system and service connectivity -- [**Connectivity Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/connectivity-service?region=all) - required for on-premises SAP S/4HANA or ECC -- [**SAP Cloud Connector**](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector) - configured to bridge on-premises systems with BTP +- [**Destination Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/destination?region=all&service_plan=lite&commercialModel=btpea) – for system and service connectivity +- [**Connectivity Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/connectivity-service?region=all) – required for on-premises SAP S/4HANA or ECC +- [**SAP Cloud Connector**](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector) – bridges on-premises systems with BTP -- **Additional services (depending on your use case):** - - [**SAP Advanced Event Mesh (AEM)**](https://discovery-center.cloud.sap/serviceCatalog/advanced-event-mesh?region=all) - enables event-driven integration between Camunda and SAP +Additional services may be required depending on your use case: -- **Required for the BTP Plugin:** - - [**PostgreSQL on SAP BTP (Hyperscaler Option)**](https://discovery-center.cloud.sap/serviceCatalog/postgresql-hyperscaler-option?region=all) +- [**SAP Advanced Event Mesh (AEM)**](https://discovery-center.cloud.sap/serviceCatalog/advanced-event-mesh?region=all) – enables event-driven integration between Camunda and SAP. ---- +Required for the BTP Plugin: + +- [**PostgreSQL on SAP BTP (Hyperscaler Option)**](https://discovery-center.cloud.sap/serviceCatalog/postgresql-hyperscaler-option?region=all) ## Authentication and connectivity - An SAP **technical user** with sufficient authorizations for the relevant S/4HANA or ECC systems -- [**Authorization and Trust Management Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all) — to manage identity and access across integration modules +- [**Authorization and Trust Management Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all) – to manage identity and access across integration modules - Secure connectivity between Camunda and SAP, configured either: - - Through **SAP Cloud Connector** for on-premises, or - - Directly via **SAP BTP services** for cloud-hosted systems. - --- + - Through **SAP Cloud Connector** for on-premises systems + - Or directly via **SAP BTP services** for cloud-hosted systems ## Tooling -- The [CSAP CLI](./csap-cli.md), a self-contained binary that runs on any platform without installation. Simply copy the binary to the target machine and run it directly. +- [**CSAP CLI**](./csap-cli.md): A self-contained binary that runs on any platform without installation. + Copy the binary to the target machine and execute it directly. diff --git a/versioned_docs/version-8.8/components/camunda-integrations/sap/eventing.md b/versioned_docs/version-8.8/components/camunda-integrations/sap/eventing.md index fe315ebb8d3..13a162f4c91 100644 --- a/versioned_docs/version-8.8/components/camunda-integrations/sap/eventing.md +++ b/versioned_docs/version-8.8/components/camunda-integrations/sap/eventing.md @@ -1,130 +1,125 @@ --- id: eventing -title: SAP Eventing with SAP Advanced Event Mesh (AEM) -description: "React on CloudEvents to/from Advanced Event Mesh in a BPMN process" +title: SAP eventing with SAP Advanced Event Mesh (AEM) +description: React to CloudEvents between Camunda and SAP Advanced Event Mesh (AEM) in a BPMN process. sidebar_label: SAP Eventing --- Receive [CloudEvents](https://cloudevents.io/) from SAP Advanced Event Mesh (AEM) and send CloudEvents to AEM. -## About SAP Eventing +## About SAP eventing -This consists of three connectors that allow bidirectional communication between Camunda and AEM. +SAP eventing uses three connectors that enable bidirectional communication between Camunda and AEM. -| Connector | Description | -| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SAP Eventing Outbound Connector | Send CloudEvents from Camunda to an AEM topic or queue endpoint. | -| SAP Eventing Message Start Event Connector | Translate an incoming CloudEvent from AEM into a [BPMN Message Start Event](/components/modeler/bpmn/message-events/message-events.md#message-start-events) triggering a new process instance. | -| SAP Eventing Intermediate Event Connector | Translate an incoming CloudEvent from AEM into a [BPMN Intermediate Catch Event](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events) allowing an active process to continue based on the event. | +| Connector | Description | +| :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SAP Eventing Outbound Connector | Sends CloudEvents from Camunda to an AEM topic or queue endpoint. | +| SAP Eventing Message Start Event Connector | Translates an incoming CloudEvent from AEM into a [BPMN Message Start Event](/components/modeler/bpmn/message-events/message-events.md#message-start-events) to trigger a new process instance. | +| SAP Eventing Intermediate Event Connector | Translates an incoming CloudEvent from AEM into a [BPMN Intermediate Catch Event](/components/modeler/bpmn/message-events/message-events.md#intermediate-message-catch-events) to allow an active process to continue based on the event. | -The integration uses `HTTP` as the transport protocol. +The integration uses **HTTP** as the transport protocol: -- The incoming connectors act as webhooks, receiving CloudEvent payloads and delivering them into process instances. -- The outbound connector sends `HTTP POST` requests to an Advanced Event Mesh [topic](https://docs.solace.com/Messaging/Guaranteed-Msg/Topic-Endpoints.htm) or [queue](https://docs.solace.com/Messaging/Guaranteed-Msg/Queues.htm) endpoints. +- Incoming connectors act as webhooks, receiving CloudEvent payloads and delivering them into process instances. +- The outbound connector sends `HTTP POST` requests to an AEM [topic](https://docs.solace.com/Messaging/Guaranteed-Msg/Topic-Endpoints.htm) or [queue](https://docs.solace.com/Messaging/Guaranteed-Msg/Queues.htm) endpoint. :::info -SAP Advanced Event Mesh uses [Solace Event Broker](https://solace.com/products/event-broker/) as its core event broker. -This means the terms **AEM** and **Solace Event Broker** can be used interchangeably when referring to core eventing functionality. +SAP Advanced Event Mesh uses [Solace Event Broker](https://solace.com/products/event-broker/) as its core event broker. +The terms **AEM** and **Solace Event Broker** can be used interchangeably when referring to eventing functionality. ::: ## Prerequisites -As `HTTP` is used as the transport protocol, AEM must be configured to use [REST messaging](https://docs.solace.com/API/REST/REST-get-start.htm). -This enables publishers and subscribers to communicate over HTTP. +Because **HTTP** is used as the transport protocol, AEM must be configured to use [REST messaging](https://docs.solace.com/API/REST/REST-get-start.htm). This enables publishers and subscribers to communicate over HTTP. -The following configuration examples in Camunda build on the Solace tutorial [Publish/Subscribe REST Messaging](https://tutorials.solace.dev/rest-messaging/publish-subscribe/), which provides detailed steps for setting up REST-based publish/subscribe messaging. +The configuration examples below build on the Solace tutorial [Publish/Subscribe REST Messaging](https://tutorials.solace.dev/rest-messaging/publish-subscribe/), which provides detailed steps for setting up REST-based publish/subscribe messaging. ## Installation -You can install the SAP Eventing connectors directly from the [Camunda Marketplace](https://marketplace.camunda.com/). +Install the SAP Eventing connectors directly from the [Camunda Marketplace](https://marketplace.camunda.com/). -## Configuration +## Configuration overview - [SAP Eventing Message Start Event Connector](#sap-eventing-message-start-event-connector) - [SAP Eventing Intermediate Event Connector](#sap-eventing-intermediate-event-connector) +- [SAP Eventing Outbound Connector](#sap-eventing-outbound-connector) ## SAP Eventing Message Start Event Connector -Inbound CloudEvents → BPMN Message +Inbound CloudEvents → BPMN message. -Applying the **SAP Eventing Message Start Event Connector** generates a unique **Webhook URL** that starts a new BPMN process instance when invoked. +Applying the **SAP Eventing Message Start Event Connector** generates a unique **webhook URL** that starts a new BPMN process instance when invoked. -![webhook URL ](./img/eventing-webhook.png) +![Webhook URL](./img/eventing-webhook.png) :::info -The Webhook URL is generated **only after the initial deployment** of the process. +The webhook URL is generated **only after the initial deployment** of the process. ::: -This Webhook URL must be registered as a target in **SAP Advanced Event Mesh (AEM)**. - +This URL must be registered as a target in **SAP Advanced Event Mesh (AEM)**. The host portion of the URL (`https://.connectors.camunda.io`) is used when configuring the **REST consumer** in AEM. ![AEM REST consumer](./img/eventing-aem-rest-consumer.png) ### Authentication -In the same REST consumer configuration, set up authentication from AEM to the Camunda Webhook endpoint. - -The credentials configured in the **Authorization** section of the Camunda connector must correspond to the **Authentication Scheme** used in AEM. +In the REST consumer configuration, set up authentication from AEM to the Camunda webhook endpoint. +The credentials configured in the **Authorization** section of the Camunda connector must match the **authentication scheme** used in AEM. ![Camunda and AEM credentials](./img/eventing-authorization.png) -### Queue Binding +### Queue binding -The path component of the Camunda Webhook URL must be used as the **POST Request Target** in the **Queue Binding** of the REST consumer. +The path component of the Camunda webhook URL must be used as the **POST request target** in the **Queue Binding** of the REST consumer. ![AEM Queue Binding](./img/eventing-aem-queue-binding.png) -### Other Configuration Options +### Other configuration options -The remaining configuration options of the **SAP Eventing Message Start Event Connector** match those of the [HTTP Webhook Connector](/components/connectors/protocol/http-webhook.md), except for one key difference: +The remaining configuration options are identical to those of the [HTTP Webhook Connector](/components/connectors/protocol/http-webhook.md), except for one key difference: -> The default **Webhook response** explicitly returns a `200` status code and an `"OK"` message body, confirming that the CloudEvent was successfully received and acknowledged by Camunda. +> The default webhook response explicitly returns a `200` status code and an `"OK"` message body, confirming that the CloudEvent was successfully received and acknowledged by Camunda. ![Remaining Incoming Webhook config](./img/eventing-incoming-other-config.png) -### Event Flow +### Event flow -When a CloudEvent is received from AEM, all **header** properties and the **body** payload are relayed as-is to the target process instance, either: +When a CloudEvent is received from AEM, all **header properties** and the **body payload** are relayed to the target process instance, either: -- At process creation, when using the **SAP Eventing Message Start Event Connector**, or -- During event correlation, when using the **SAP Eventing Intermediate Event Connector**. +- At process creation (Message Start Event), or +- During event correlation (Intermediate Event). This ensures that message attributes and payload data from AEM are preserved end-to-end within the Camunda process. ## SAP Eventing Intermediate Event Connector -### Correlate CloudEvents as BPMN Messages - -The **SAP Eventing Intermediate Event Connector** injects a CloudEvent from **SAP Advanced Event Mesh (AEM)** into an _active_ Camunda BPMN process instance. +### Correlate CloudEvents as BPMN messages -It does this by leveraging the BPMN principle of [**message correlation**](/components/connectors/protocol/http-webhook.md#correlation). +The **SAP Eventing Intermediate Event Connector** injects a CloudEvent from AEM into an active Camunda process instance using [message correlation](/components/connectors/protocol/http-webhook.md#correlation). -Any CloudEvent property can be used as a **correlation key** to map incoming event data to the correct process instance. +Any CloudEvent property can be used as a **correlation key** to match incoming event data to the correct process instance. -### Correlation via CloudEvent Body +### Correlation via CloudEvent body -The configuration options of the **SAP Eventing Message Start Event Connector** and the **SAP Eventing Intermediate Event Connector** are identical, except that the _Intermediate Event_ requires an additional **Correlation** section to be configured. +The configuration options of the **Message Start** and **Intermediate Event** connectors are identical, except that the intermediate event requires an additional **Correlation** section. ![Intermediate Message Correlation](./img/eventing-intermediate-correlation.png) -- In the example above, the process variable `ENCOMGridID` is expected to exist within the process instance. +- In the example above, the process variable `ENCOMGridID` must exist within the process instance. - Its value is compared against the CloudEvent payload (`request.body.FlynnLocationID`). -- If both values match, the CloudEvent is considered to be the published BPMN message that is correlated to the corresponding process instance. +- If both values match, the CloudEvent is correlated to that process instance. -### Correlation via CloudEvent Metadata +### Correlation via CloudEvent metadata Since **HTTP** is used as the transport protocol, the [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) requires all CloudEvent metadata to be passed as **HTTP headers**. -In addition, AEM prepends all user properties with the prefix `Solace-User-Property-` to persist them in its event engine. For example, a CloudEvent with the property `"ce-id"` is represented in AEM as the HTTP header named `Solace-User-Property-ce-id` +AEM prepends all user properties with the prefix `Solace-User-Property-`. +For example, the CloudEvent property `ce-id` is represented as the HTTP header `Solace-User-Property-ce-id`. -This means that to perform BPMN message correlation based on CloudEvent metadata, reference the corresponding **HTTP header name** including the `Solace-User-Property-` prefix. +To correlate on metadata, reference the header name including this prefix. -#### Example: CloudEvent HTTP Message - -The following is an example of a CloudEvent HTTP request received by Camunda: +#### Example: CloudEvent HTTP message ```json { @@ -132,70 +127,55 @@ The following is an example of a CloudEvent HTTP request received by Camunda: "body": { "FlynnLocationID": "34.0522,-118.2437" }, "headers": { "host": ".connectors.camunda.io", - "x-request-id": "956de0835ad61a211a20e4755315b413e", - "x-real-ip": "12.123.123.456", - "x-forwarded-host": ".connectors.camunda.io", - "x-forwarded-port": "443", - "x-forwarded-proto": "https", - "x-forwarded-scheme": "https", - "x-scheme": "https", - "content-length": "44", "authorization": "Basic CaMUnDakZW1v", - "cache-control": "no-cache", "content-type": "application/json", - "solace-delivery-mode": "Persistent", "solace-user-property-ce-specversion": "1.0", "solace-user-property-ce-type": "sap.s4.beh.encom.grid.program.v1", "solace-user-property-ce-source": "/alan/pager/buzz", "solace-user-property-ce-subject": "CLU-2.0", "solace-user-property-ce-id": "Argon-T-01", "solace-user-property-ce-time": "2018-04-05T03:56:24Z", - "solace-user-property-ce-datacontenttype": "application/json", - "user-agent": "Solace_PubSub+_Enterprise/10.11.1.167" - }, - "params": {} - }, - "connectorData": {}, - "documents": [] + "solace-user-property-ce-datacontenttype": "application/json" + } + } } ``` -In this example, to correlate the CloudEvent `ce-id` property to a process instance, reference it as: -`` request.headers.`solace-user-property-ce-id` `` in the header field. +To correlate on the `ce-id` property, use `request.headers.solace-user-property-ce-id`. ![Mapping to CloudEvent meta data](./img/eventing-correlation-ce-headers.png) :::tip -Note the "backticks" notation of the header value `` request.headers.`solace-user-property-ce-id` `` to escape the dashes in the header field name. +Use backticks to escape dashes in the header name, for example: +`` request.headers.`solace-user-property-ce-id` ``. ::: -### SAP Eventing Outbound Connector +## SAP Eventing Outbound Connector -The **SAP Eventing Outbound Connector** allows you to send CloudEvents to **SAP Advanced Event Mesh (AEM)** using its **REST messaging** capability. It uses the REST messaging capability of AEM to publish the CloudEvent via a `HTTP POST` request. +The **SAP Eventing Outbound Connector** allows you to send CloudEvents to AEM using its REST messaging capability. It publishes the event using an `HTTP POST` request. ![SAP eventing outbound connector configuration](./img/eventing-outbound-connector.png) ### Endpoint -The **Endpoint** field specifies the URL of your AEM Event Broker. +The **Endpoint** field specifies the URL of your AEM event broker. -You can find this URL in the Advanced Event Mesh's web interface by navigating to: +You can find this URL in AEM’s web interface: > **Cluster Manager → Your Cluster → (Service Details) → Connect → Connect with Java → Solace REST Messaging API** -On the right-hand side of the interface is the **FQDN** (Fully Qualified Domain Name) of your AEM broker instance. +The **FQDN** (fully qualified domain name) is shown on the right-hand side. ![FQDN of the AEM REST messaging API](./img/eventing-aem-rest-fqdn.png) -### Topic / Queue - -Specify the target **topic** or **queue** path where the CloudEvent will be published. +### Topic / queue -Neither value should begin with a `/` — the connector includes a validation check to prevent this. +Specify the target **topic** or **queue** path where the CloudEvent will be published. +Do not begin the path with `/` — the connector includes a validation check to prevent this. ### Authorization -Select one of the following authorization methods: +Supported authorization methods: - `None` - `API Key` @@ -205,13 +185,14 @@ Select one of the following authorization methods: ### CloudEvent -While CloudEvent metadata (for example, `ce-id` or `ce-subject`) is automatically handled by the AEM broker—including the required `Solace-User-Property-` prefix, you only need to configure the **standard CloudEvent attributes** in this connector. +CloudEvent metadata (e.g., `ce-id`, `ce-subject`) is automatically handled by the AEM broker, including the required `Solace-User-Property-` prefix. +Configure only the standard CloudEvent attributes in the connector. -The CloudEvent data is serialized into a **JSON body**, and both the **metadata** and **data** fields support [FEEL expressions](/components/modeler/feel/what-is-feel.md) for dynamic values. +The CloudEvent data is serialized into a **JSON body**, and both metadata and data fields support [FEEL expressions](/components/modeler/feel/what-is-feel.md) for dynamic values. ![Eventing Outbound CloudEvent](./img/eventing-outbound-cloudevent.png) -### Other Configuration Options +### Other configuration options All remaining options are identical to those of the [REST Connector](/components/connectors/protocol/rest.md), including: diff --git a/versioned_docs/version-8.8/components/camunda-integrations/sap/prerequisites.md b/versioned_docs/version-8.8/components/camunda-integrations/sap/prerequisites.md index acd1c73cdfb..cdbfc518c1a 100644 --- a/versioned_docs/version-8.8/components/camunda-integrations/sap/prerequisites.md +++ b/versioned_docs/version-8.8/components/camunda-integrations/sap/prerequisites.md @@ -1,49 +1,48 @@ --- id: prerequisites title: Prerequisites -description: "Checklist of Camunda, SAP, authentication, and connectivity requirements before deploying the SAP integration modules." +description: "Review the required Camunda components, SAP services, authentication setup, and connectivity before deploying the SAP integration modules." --- -Before setting up the SAP integration, ensure that the following requirements are met. +Before setting up the SAP integration, ensure the following requirements are met. ## Camunda setup -- **OData and RFC Connectors:** 8.6+ +- **OData and RFC connectors:** 8.6+ - **BTP Plugin:** 8.6+ -- **Advanced Event Mesh Integration:** 8.6+ +- **Advanced Event Mesh integration:** 8.6+ -Works with both **SaaS** and **Self-Managed** deployments: +Compatible with both **SaaS** and **Self-Managed** deployments: -- **SaaS:** Configure [hybrid connectors](/components/connectors/use-connectors-in-hybrid-mode.md) to securely connect to SAP systems. -- **Self-Managed:** Ensure outbound connectivity from your environment to SAP BTP. +- **SaaS:** Use [hybrid connectors](/components/connectors/use-connectors-in-hybrid-mode.md) to securely connect to SAP systems. +- **Self-Managed:** Ensure outbound network connectivity from your environment to SAP BTP. ## SAP setup -You’ll need an **SAP BTP subaccount** with the following services enabled: +You need an **SAP BTP subaccount** with these services enabled: - [**Cloud Foundry Runtime**](https://discovery-center.cloud.sap/serviceCatalog/cloud-foundry-runtime?region=all) -- [**Destination Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/destination?region=all&service_plan=lite&commercialModel=btpea) - for system and service connectivity -- [**Connectivity Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/connectivity-service?region=all) - required for on-premises SAP S/4HANA or ECC -- [**SAP Cloud Connector**](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector) - configured to bridge on-premises systems with BTP +- [**Destination Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/destination?region=all&service_plan=lite&commercialModel=btpea) – for system and service connectivity +- [**Connectivity Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/connectivity-service?region=all) – required for on-premises SAP S/4HANA or ECC +- [**SAP Cloud Connector**](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector) – bridges on-premises systems with BTP -- **Additional services (depending on your use case):** - - [**SAP Advanced Event Mesh (AEM)**](https://discovery-center.cloud.sap/serviceCatalog/advanced-event-mesh?region=all) - enables event-driven integration between Camunda and SAP +Additional services may be required depending on your use case: -- **Required for the BTP Plugin:** - - [**PostgreSQL on SAP BTP (Hyperscaler Option)**](https://discovery-center.cloud.sap/serviceCatalog/postgresql-hyperscaler-option?region=all) +- [**SAP Advanced Event Mesh (AEM)**](https://discovery-center.cloud.sap/serviceCatalog/advanced-event-mesh?region=all) – enables event-driven integration between Camunda and SAP. ---- +Required for the BTP Plugin: + +- [**PostgreSQL on SAP BTP (Hyperscaler Option)**](https://discovery-center.cloud.sap/serviceCatalog/postgresql-hyperscaler-option?region=all) ## Authentication and connectivity - An SAP **technical user** with sufficient authorizations for the relevant S/4HANA or ECC systems -- [**Authorization and Trust Management Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all) — to manage identity and access across integration modules +- [**Authorization and Trust Management Service (Free)**](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all) – to manage identity and access across integration modules - Secure connectivity between Camunda and SAP, configured either: - - Through **SAP Cloud Connector** for on-premises, or - - Directly via **SAP BTP services** for cloud-hosted systems. - --- + - Through **SAP Cloud Connector** for on-premises systems + - Or directly via **SAP BTP services** for cloud-hosted systems ## Tooling -- The [CSAP CLI](./csap-cli.md), a self-contained binary that runs on any platform without installation. Simply copy the binary to the target machine and run it directly. +- [**CSAP CLI**](./csap-cli.md): A self-contained binary that runs on any platform without installation. + Copy the binary to the target machine and execute it directly.