Connecting an On-premise CoreMedia Instance to the Event Hub Service

Last updated 2 months ago

Connecting an on-premise instance.

Table of Contents

Introduction
Prerequisites
Register your CoreMedia instance
Downloading the Event Hub Repository Listener
Configuring and installing the Event Hub Repository Listener
Complete Event Hub Registration
Actuator Endpoints

Introduction

Connecting an on-premise CoreMedia Content Cloud instance to the Event Hub Service requires the installation of a custom component, the Event Hub Repository Listener, and additional configuration and registration steps. The required procedure is detailed in the following sections.

Prerequisites

Getting a license for the Event Hub Service is mandatory but not detailed in this document. Please contact your CoreMedia representative for more information.

Using the Event Hub Service requires running at least CoreMedia Content Cloud 11. The required component at the on-premise side is the Event Hub Repository Listener, which is provided as a prebuilt container image. One instance of this listener is required to run on the management side and connect to the Content Management Server, and a second instance is required to run on the delivery side and connect to the Master Live Server. Both listeners need to connect to the Internet to be able to communicate with the Event Hub Service and CoreMedia Authentication Service.

Register your CoreMedia instance

Each CoreMedia Content Cloud instance that will be connected to the Event Hub Service needs a separate registration.

To register your instance with the Event Hub Service, please contact CoreMedia support and provide them with your customer details and the name of the instance, for example prod, qa, etc. As response support will provide you in a secure way with the following login credentials that you need for configuring the Event Hub Repository Listener instances:

TENANT_ID: a unique identifier for your connecting instance, for example t3d6awk5
COGNITO_USERNAME: the username for the CoreMedia Authentication service
COGNITO_PASSWORD: the password for user COGNITO_USERNAME

These login credentials are required for the listener to get a JWT to access the Event Hub Service.

Downloading the Event Hub Repository Listener

The images for the Event Hub Repository Listener are available on the CoreMedia Download Area.

Two versions are available, one for CMCC 11 and one for CMCC 12. Please download the version that matches your CoreMedia Content Cloud version and install the image to a local Docker registry that is accessible to your deployment tasks. The Docker Compose scripts in the next chapter assume that the image is available in the same registry that hosts the Blueprint images you built yourself.

Configuring and installing the Event Hub Repository Listener

The following paragraphs show how to integrate the Event Hub Repository Listener into the CoreMedia Blueprint’s Docker Compose setup. If you use a different deployment method, these examples provide all the details to adapt your setup accordingly.

Add Compose file

Add a file event-hub.yml to your compose files with the following content:

# default logging configuration
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

# default environment variables for development
x-development-boot-envs:
  &development-boot-envs
  JAVA_DEBUG: "${JAVA_DEBUG:-false}"
  # enable entrypoint debugging i.e. set -x
  DEBUG_ENTRYPOINT: "${DEBUG_ENTRYPOINT:-false}"
  # writes heapdumps to /coremedia/heapdumps on oom exceptions. restart the container or mount a volume to
  # that directory to inspect the heapdumps
  HEAP_DUMP_ON_OOM: "${HEAP_DUMP_ON_OOM:-true}"
  JAVA_OPTS: "-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv4Addresses -XX:MetaspaceSize=64m -XX:MaxMetaspaceSize=192m -XX:TieredStopAtLevel=1"
  SPRING_PROFILES_ACTIVE: dev

x-default-boot-healthcheck:
  &default-boot-healthcheck
  test: [ "CMD", "curl", "-Lf", "http://localhost:8081/actuator/health" ]
  interval: 10s
  timeout: 10s
  retries: 10
  start_period: ${HEALTHCHECK_START_PERIOD_TIMEOUT:-180s}

services:
  event-hub-listener-preview:
    image: ${REPOSITORY_PREFIX:-coremedia}/event-hub-repository-listener:${EVENT_HUB_REPOSITORY_LISTENER_TAG:-latest}
    container_name: event-hub-listener-preview
    restart: always
    logging: *default-logging
    networks:
      - backend
    read_only: true
    cap_drop:
      - ALL
    ports:
      - 46081:8081
    environment:
      <<: *development-boot-envs
      SPRING_APPLICATION_NAME: 'event-hub-listener-preview'
      REPOSITORY_URL: http://content-management-server:8080/ior
      REPOSITORY_WORKFLOW_CONNECT: true
      MONGODB_CLIENTURI: mongodb://coremedia:coremedia@mongodb:27017
      EVENTHUB_TENANTID: ${EVENTHUB_TENANTID:?EVENTHUB_TENANTID must be set}
      EVENTHUB_SOURCEID: preview
      EVENTHUB_AWS_GATEWAYURL: ${EVENTHUB_GATEWAYURL:-https://api-01.event-hub.coremedia.io/listener/v1}
      EVENTHUB_AWS_COGNITO_USERNAME: ${EVENTHUB_COGNITO_USERNAME:?EVENTHUB_COGNITO_USERNAME must be set}
      EVENTHUB_AWS_COGNITO_PASSWORD: ${EVENTHUB_COGNITO_PASSWORD:?EVENTHUB_COGNITO_PASSWORD must be set}
      HEAP_DUMP_FILENAME: event-hub-listener-preview-heapdump
    volumes:
      - heapdumps:/coremedia/heapdumps
    healthcheck: *default-boot-healthcheck
    depends_on:
      content-management-server:
        condition: service_healthy
      workflow-server:
        condition: service_healthy

  event-hub-listener-live:
    image: ${REPOSITORY_PREFIX:-coremedia}/event-hub-repository-listener:${EVENT_HUB_REPOSITORY_LISTENER_TAG:-latest}
    container_name: event-hub-listener-live
    restart: always
    logging: *default-logging
    networks:
      - backend
    read_only: true
    cap_drop:
      - ALL
    ports:
      - 46181:8081
    environment:
      <<: *development-boot-envs
      SPRING_APPLICATION_NAME: 'event-hub-listener-live'
      REPOSITORY_URL: http://master-live-server:8080/ior
      EVENTHUB_TENANTID: ${EVENTHUB_TENANTID:?EVENTHUB_TENANTID must be set}
      EVENTHUB_SOURCEID: live
      EVENTHUB_AWS_GATEWAYURL: ${EVENTHUB_GATEWAYURL:-https://api-01.event-hub.coremedia.io/listener/v1}
      EVENTHUB_AWS_COGNITO_USERNAME: ${EVENTHUB_COGNITO_USERNAME:?EVENTHUB_COGNITO_USERNAME must be set}
      EVENTHUB_AWS_COGNITO_PASSWORD: ${EVENTHUB_COGNITO_PASSWORD:?EVENTHUB_COGNITO_PASSWORD must be set}
      HEAP_DUMP_FILENAME: event-hub-listener-live-heapdump
    volumes:
      - heapdumps:/coremedia/heapdumps
    healthcheck: *default-boot-healthcheck
    depends_on:
      master-live-server:
        condition: service_healthy

  traefik:
    environment:
      ACTUATOR_EVENTHUB_LISTENER_PREVIEW: 'event-hub-listener-preview'
      ACTUATOR_EVENTHUB_LISTENER_LIVE: 'event-hub-listener-live'

  overview:
    environment:
      EVENTHUB_LISTENER_ENABLED: "true"

Add this file to the end of the COMPOSE_FILE variable in your .env file, for example:

COMPOSE_FILE=compose/default.yml:compose/development.yml:compose/development-local.yml:compose/event-hub.yml

Add Event Hub Configuration

Add the following configuration settings, which you received from CoreMedia support, to your .env file:

# Event Hub Configuration
EVENTHUB_TENANTID=<TENAND_ID>
EVENTHUB_COGNITO_USERNAME=<COGNITO_USERNAME>
EVENTHUB_COGNITO_PASSWORD='<COGNITO_PASSWORD>'
# The URL of the Event Hub Gateway, only required if you are
# not assigned to the default Event Hub instance
# EVENTHUB_GATEWAYURL=

If support provided you with a URL different from the default Event Hub Gateway (https://api-01.event-hub.coremedia.io/listener/v1), uncomment and configure the variable EVENTHUB_GATEWAYURL accordingly.

Update the Blueprint Overview Page

To add the Event Hub Repository Listener to the service section of the overview page, modify the following files.

Add this to Blueprint workspace file actuator-configuration.yml after {{ $services := append $services (env "ACTUATOR_COMMERCE_ADAPTER_WCS" | default "ignore") }}:

{{ $services := append $services (env "ACTUATOR_EVENTHUB_LISTENER_PREVIEW" | default "ignore") }}
{{ $services := append $services (env "ACTUATOR_EVENTHUB_LISTENER_LIVE" | default "ignore") }}

Add this to Blueprint workspace file actuators.html.tmpl after the commerce adapter blocks:

  {{ if eq (getv "/eventhub/listener/enabled" "true") "true" }}
  <tr>
    <td><a href="http://{{ getv "/environment/fqdn" }}:46081/actuator" data-cm-test="">Event Hub Listener Preview</a></td>
    <td>
      <a href="/event-hub-listener-preview/info" target="_blank">Info</a> ·
      {{ if eq (getv "/grafana/enabled" "false") "true" }}
        <a href="https://grafana.{{ getv "/environment/fqdn" }}/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Loki%22,%7B%22exemplar%22:true,%22expr%22:%22%7Bcontainer%3D%5C%22event-hub-listener-preview%5C%22%7D%22%7D%5D" target="_blank">App Log</a> ·
      {{ else }}
        <a href="/event-hub-listener-preview/logfile" target="_blank">App Log</a> ·
      {{ end }}
      <a href="/event-hub-listener-preview/env" target="_blank">Env</a> ·
      <a href="/event-hub-listener-preview/configprops" target="_blank">Config</a>
    </td>
    <td>
      <a href="/event-hub-listener-preview/health" target="_blank" class="health_check"><span class="check_unknown">Unknown</span></a>
    </td>
  </tr>
  <tr>
    <td><a href="http://{{ getv "/environment/fqdn" }}:46181/actuator" data-cm-test="">Event Hub Listener Live</a></td>
    <td>
      <a href="/event-hub-listener-live/info" target="_blank">Info</a> ·
      {{ if eq (getv "/grafana/enabled" "false") "true" }}
        <a href="https://grafana.{{ getv "/environment/fqdn" }}/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Loki%22,%7B%22exemplar%22:true,%22expr%22:%22%7Bcontainer%3D%5C%22event-hub-listener-live%5C%22%7D%22%7D%5D" target="_blank">App Log</a> ·
      {{ else }}
        <a href="/event-hub-listener-live/logfile" target="_blank">App Log</a> ·
      {{ end }}
      <a href="/event-hub-listener-live/env" target="_blank">Env</a> ·
      <a href="/event-hub-listener-live/configprops" target="_blank">Config</a>
    </td>
    <td>
      <a href="/event-hub-listener-live/health" target="_blank" class="health_check"><span class="check_unknown">Unknown</span></a>
    </td>
  </tr>
  {{end}}

Complete Event Hub Registration

After you have completed the steps above, deploy and start the listener instances.

The Event Hub Listeners should complete the startup with the following log message:

2024-05-21 09:41:40 [INFO]  (main) com.coremedia.eventhub.repository.listener.EventHandlerLifecycleController [internal] - Started

If no errors occur for approximately 5 minutes, it’s time to complete the registration by enabling the event streams you want to subscribe to.

Contact CoreMedia support and provide them with the following information:

TENANT_ID: the tenant ID you received from support
SOURCE_ID: preview and/or live
EVENT_STREAM_ID: the event stream you want to enable, CONTENT, NOTIFICATION and/or WORKFLOW

The support team will then enable the event streams for your tenant.

Continue with creating your subscriptions as described in Event Hub Subscription Service.

Actuator Endpoints

The Event Hub Repository Listener uses Spring Boot Actuator Endpoints to provide additional details about its state:

/actuator/health: State of the internal handlers for the different event streams (attribute listenerHealth)
/actuator/listener: Event counters and last committed timestamp for the different event streams

Is this page useful?

campaigns

contact center and analytics studio

engagement cloud

event hub service

image transformation

ingest service