Ringier Event Bus

# Send events

# Get credentials

The first step is to register as a node on the bus to get credentials. Nodes are entities that emit events, receive events or both.

  • Log in to the bus admin. You will find the link in the top-right corner of this page.
  • On the Nodes page, click on the button Add New.
  • After providing a name, description and contact details, enable the option to Emit events.
  • Choose a username and password. Together with the node id, they are the credentials required to authenticate before sending events to the bus.

We suggest that you register the node on both the staging and production environments.

# Using a client library

One of the bus' reasons to exist is to reduce duplication of efforts across teams. With this idea in mind, we encourage you to use and add to the client librairies available to send events to the bus. We currently have a Laravel package available as well as a plugin for WordPress:

Reach out to the bus team if you need support or to add your contribution to the list above.

If you are building a library, or integrating directly with the bus, you can follow the steps below.

# Bus URL

Here is the bus base URL for the staging and production environments:

  • Staging: https://bus.staging.ritdu.tech/v1
  • Production: https://bus.ritdu.net/v1

# Authenticate

Call the /login endpoint with your username, password and node id in a JSON object in order to retrieve a token.

# Endpoint

POST /login

# Parameters

# Version 2.0.0 (current)

Name Type Required
username string ✓
password string ✓
node_id string ✓

# Version 1.0.0 (accepted until end of 2022)

Name Type Required
username string ✓
password string ✓
venture_config_id string ✓

# Call example

{
  "username": "Jack",
  "password": "hd8kjd-JNH;sE9KEu8y6",
  "node_id": "04f9f5d9-d84c-4636-acae-2067eee4d81f"
}

# Responses

The token retrieved must be cached and included as x-api-key in the header when sending events.

The /login endpoint must only be called again to retrieve a new token if it expires, i.e. you get a 401 response code from the bus when sending an event.

# Send events

To send event(s) into the bus, POST an array of events to the /events endpoint.

# Endpoint

POST /events

# Parameters

# Version 2.0.0 (current)

Name Type Required Description
events array of strings ✓ Array of event names.
from string ✓ Your node id. It must be the same as the one used to authenticate.
reference string ✓ A unique reference for the event instance.
created_at string ✓ Date and time when the event was created, including timezone, following ISO 8601 (YYYY-MM-DDThh:mm:ss.sTZD) (opens new window), e.g.: "2022-05-09T16:59:14+02:00"
payload object ✓ JSON payload relevant to the specific event(s). See the specifications.
version string ✓ Event version. The version described here is "2.0.0".
route string Together with the event name, this field can be used to determine where the event will be routed. Optional and defaulted to empty. Learn more.

# Version 1.0.0 (accepted until end of 2022)

Name Type Required Description
events array of strings ✓ Array of event names.
venture_config_id string ✓ Your node id, formerly called venture config id. It must be the same as the one used to authenticate.
venture_reference string ✓ A unique reference for the event instance.
created_at string ✓ Date and time when the event was created, including timezone, following ISO 8601 (YYYY-MM-DDThh:mm:ss.sTZD) (opens new window), e.g.: "2022-05-09T16:59:14+02:00"
culture string ✓ Code (opens new window) representation of the language and culture active on the system when the event was created
action_type string ✓ Who or what initiated the event. E.g.: "user", "admin", "api", "system", "app", "migration" or "other".
action_reference string Optional reference to who created the event where relevant to the action type, such as the user id.
payload object ✓ JSON payload relevant to the specific event(s). See the specifications.
version string Event version. Optional and defaulted to "1.0.0".
route string Together with the event name, this field can be used to determine where the event will be routed. Optional and defaulted to empty.

# Call example

[
  {
    "events": ["EventName"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0",
    "route": ""
  }
]

# Responses

# Event and payload specifications

To use existing services, and for services to be able to rely on consistent events across different ventures, you can leverage pre-defined event names and payload schemas:

Feel free to add more events and payload schemas to these documents and to contact Delphine from the Bus team if you have any questions.

# Batch events

If you want to send several events with the same payload, you can send them in one object.
Example of use case: one user creates an account, ticks the newsletter subscription box and is logged in automatically.

[
  {
    "events": ["UserCreated", "NewsletterSubscribed", "UserLogin"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {
      "user": {}
    },
    "version": "2.0.0"
  }
]

If you batch several events each with its own payload, you can send several objects:

[
  {
    "events": ["Event1"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0"
  },
  {
    "events": ["Event2"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123457",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0"
  },
]

# Event routing

You can define to which nodes your events are routed by adding destinations in the admin.

  • Log in to the bus admin. You will find the link in the top-right corner of this page.
  • On the Nodes page, select your sending node in the list.
  • Access the menu Event Destinations.
  • Add destination(s) for your event(s).

# Filtering events by name

You can select events to route to a destination by filtering on the event name.

Wild cards: The event name accepts ? as a wild card to represent one character and * as a wild card to represent one or more characters.
Example: "Listing*" can be used to route "ListingCreated", "ListingUpdated" and "ListingDeleted" in one trigger.

# Filtering events by route

Optionally, you can select events to route to a destination by filtering on the route.

Example of use case: You are working with a new third party and you need to import all articles currently online on your site into their content library. You can write a script to trigger "ArticleCreated" events for all online articles with a specific route value, and use this route value to ensure that those events only reach the service in charge of syncing content with this new third party.

To filter events by route, you first need to access the Details and Settings page and choose to define event destinations based on Event name and route. On the Event Destinations page, you will then be able to specify the route.

Note: An empty route will only match events where the route is an empty string or not specified. * will match any route, except special bus routes prefixed with "bus-".

# Authentication to the receiving node

If authentication is required by the receiving node, you will find an Authentication in the destination details. Contact the receiving node to get credentials. Then, enter the name and value in the corresponding fields. The bus will insert them in the headers when calling the node's endpoint.

# Configuration data

The bus allows to store configuration data such as settings and credentials to communicate with third parties in your name, so that you don't have to include them in the payload of every event.

If the receiving node requires such data, you will find a Configuration data section in the destination details.

Depending on the receiving node settings, the data will either

  • be appended to each event received by the bus and routed to the receiving node,
  • or sent to the receiving node when updated, and stored by the receiving node.

You may contact the receiving node to confirm the expected data and format.

# Inheritance

All nodes inherit destinations (including configuration data) defined at the bus level and at the parent node level, if any. To define a parent node and access the details of inherited settings, click on Inherited destinations in the top right corner of the Event Destinations page.

Some destinations are defined at the bus level so that all nodes benefit from default functionalities such as event counting and monitoring, storing of the last 100 events sent for debugging (displayed on the Events and Metrics page) or the automatic sending of notifications to Slack.

You may define a parent node if you need to set up the same destinations (including configuration data) for several nodes.

If you wish to disable an inherited destination, you can create the same destination at the node level and disable it.

# Queueing and retrying

Events must be queued on the sender side to achieve the lowest risk of failure. We recommend implementing basic queuing with services such as AWS SQS or any other queuing system readily available in your development framework.

Should the client be unable to send the event to the bus (possible reasons include connectivity issues), it shall retry using exponential backoff.

# Receive a response

Some receiving nodes may communicate information back to you. You then need to implement a REST endpoint accepting events sent via a POST call. Learn how to receive events.

# Testing

You can test your events' structure and confirm to which nodes they will be routed.

# Validate event structure

Event validation enables you to:

  • Check if the event complies with the structure described in the send events section of this page.
  • If the event is one of the events specified in the specifications and the payload schema has been added to the event validator source code (opens new window), it will check that the payload structure complies with the specification. You are welcome to contribute to the payload schemas' definition.

# From the admin

Click on Event Tester in the admin menu, paste an event and select the action Validate event structure. The validation feedback will appear below.

# From your application

Send an event to the bus from your application using the route "bus-validation" like in the example below. Your event will not be routed to any nodes. The bus response will indicate whether the event is valid, whether the payload complies with the specifications (if the payload schema is defined) and what the errors are.

# Test event routing

The admin can confirm to which nodes an event will be routed.

  • Click on Event Tester in the admin menu
  • Paste an event, or simply enter an event name and eventually a route value
  • Select the action Dry run (verify destinations)
  • Submit and find out to which nodes the event would be routed.

# View events sent

You can see the last 100 events sent received by the bus.

  • Click on Events and Metrics in the admin menu and look at Recent events emitted.