Search

    Using SAP Event Mesh in Cloud Foundry

    SAP Event Mesh is the default offering for messaging in SAP Business Technology Platform (SAP BTP). CAP provides out-of-the-box support for SAP Event Mesh, and automatically handles many things behind the scenes, so that application coding stays agnostic and focused on conceptual messaging.

    The following guide is based on a productive (paid) account on SAP BTP. It’s not supported to use the trial offering of SAP Event Mesh.

    Prerequisite: Create an Instance of SAP Event Mesh

    Important: You don’t need to manually create queues or queue subscriptions as CAP takes care for that automatically based on declared events and subscriptions.

    Use enterprise-messaging

    Add the following to your package.json to use SAP Event Mesh:

    "cds": {
      "requires": {
        "messaging": {
          "[production]": { "kind": "enterprise-messaging" },
        }
      }
    }
    

    Learn more about cds.env profiles

    Behind the Scenes, the enterprise-messaging implementation handles these things automatically and transparently:

    • Creation of queues & subscriptions for event receivers
    • Handling all broker-specific handshaking and acknowledgments
    • Constructing topic names as expected by the broker
    • Wire protocol envelopes, that is, CloudEvents

    Optional: Add namespace Prefixing Rules

    SAP Event Mesh documentation recommends to prefix all event names with the service instance’s configured namespace, both, when emitting as well as when subscribing to events. If you followed these rules, add corresponding rules to your configuration in package.json to have CAP’s messaging service implementations enforcing these rules automatically:

    "cds": {
      "requires": {
        "messaging": {
          "publishPrefix": "$namespace/",
          "subscribePrefix": "$namespace/"
        }
      }
    }
    

    The variable $namespace is resolved from your SAP Event Mesh service instance’s configured namespace property.

    Run Tests in hybrid Setup

    Before deploying to the cloud, you may want to run some ad-hoc tests with a hybrid setup, that is, keep running the CAP services locally, but using the SAP Event Mesh instance from the cloud. Do that as follows:

    1. Configure CAP to use the enterprise-messaging-shared implementation in the reviews and bookstore sample:
    "cds": {
      "requires": {
        "messaging": {
          "[hybrid]": { "kind": "enterprise-messaging-shared" }
        }
      }
    }
    

    The enterprise-messaging-shared variant is for single-tenant usage and uses AMQP by default. Thus, it requires much less setup for local tests compared to the production variant, which uses HTTP-based protocols by default.

    1. Add @sap/xb-msg-amqp-v100 as dependency:
    npm add @sap/xb-msg-amqp-v100
    

    Learn more about SAP Event Mesh (Shared).

    1. Create a service key for your Event Mesh instance → see help.sap.com

    2. Copy its content into a VCAP_SERVICES entry in a ./default-env.json, in the reviews and bookstore sample, file like that:

    {
      "VCAP_SERVICES": {
        "enterprise-messaging": [{
          "label": "enterprise-messaging",
          "credentials":
            // ... Insert content of service key here! ...
        }]
      }
    }
    

    Learn more about default-env.json.

    1. Run your services in separate terminal shells with the hybrid profile:
    cds watch reviews --profile hybrid
    
    cds watch bookstore --profile hybrid
    

    Learn more about cds.env profiles.

    1. Test your app as described in the messaging guide.

    CAP Automatically Creates Queues and Subscriptions

    When you run the services with a bound instance of SAP Event Mesh as documented in a previous section, CAP messaging service implementations will automatically create a queue for each receiver process. The queue name is chosen automatically and the receiver’s subscriptions added.

    Optional: Configure Queue Names

    In case you want to manage queues yourself, use config option queue.name as follows:

    "cds": {
      "requires": {
        "messaging": { // ...
          "queue": { "name": "$namespace/my/own/queue" }
        }
      }
    }
    

    In both cases — automatically chosen queue names or explicitly configured ones — if the queue already exists it’s reused, otherwise it’s created.

    Learn more about queue configuration options.

    Deploy to the Cloud (with MTA)

    A general description of how to deploy CAP applications to SAP BTP’s Cloud Foundry, can be found in the Deploy to Cloud* guide. As documented there, MTA is frequently used to deploy to SAP BTP. Follow these steps to ensure binding of your deployed application to the SAP Event Mesh instance.

    1. Specify Binding to SAP Event Mesh Instance

    Add SAP Event Mesh’s service instance’s name to the requires section of your CAP application’s module, and a matching entry to the resources section, for example:

    modules:
      - name: bookstore-srv
        requires:
          - name: <Event Mesh Service Instance - Name>
    
    resources:
      # SAP Event Mesh
      - name: <Event Mesh Service Instance - Name>
        type: org.cloudfoundry.managed-service
        parameters:
          service: enterprise-messaging
          service-plan: <Event Mesh Service Instance - Plan>
    

    Learn more about using MTA.

    Make sure to use the exact name and service-plan used at the time creating the service instance you want to use.

    2. Optional: Auto-Create SAP Event Mesh Instances

    MTA can also create the service instance automatically. To do so, you need to additionally provide a service descriptor file and reference that through the path parameter in the resources section:

    resources:
      # SAP Event Mesh as above...
        parameters:
          path: ./<Event Mesh Service Descriptor JSON file>
    

    Learn more about Service Descriptors for SAP Event Mesh.

    Show/Hide Beta Features