Skip to main content

Generator API

Overview

API for the EventCatalog Amazon EventBridge generator.

Example eventcatalog.config.js file

eventcatalog.config.js
---
import path from 'path';
import url from 'url';

const __dirname = path.dirname(url.fileURLToPath(import.meta.url));

/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
export default {
title: 'OurLogix',
tagline: 'A comprehensive logistics and shipping management company',
organizationName: 'OurLogix',
homepageLink: 'https://eventcatalog.dev/',
landingPage: '',
editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
trailingSlash: false,
base: '/',
logo: {
alt: 'EventCatalog Logo',
src: '/logo.png',
text: 'OurLogix',
},
docs: {
sidebar: {
showPageHeadings: true,
},
},
generators: [
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
services: [
// Maps exact events to the service
{ id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], receives:[{ detailType: "InventoryAdjusted"}]}] },

// Filter by source (all events that match the source get assigned). This example shows any event matching the source
// "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
{ id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders"}], receives:[{ detailType: "UserCheckedOut"}] },


// This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],

// all services are mapped to this domain
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
],
// Just import all events into the Catalog from a registry
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas'
},
],
// Example using optional credentials
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
credentials: {
accessKeyId: 'X',
secretAccessKey: 'X',
accountId: 'X',
},
},
],
],
};

warning

When importing node modules into your eventcatalog.config.js file, you need to import the entire package.

import path from "path"; //work

import { join } from "path"; // will not work

This is currently a limitation and is being looked at. Any problems or issues feel free to raise a GitHub issue.

Required fields

region

  • Type: String

The region of your schema registry.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas'
},
],

registryName

  • Type: String

The EventBridge registry name for your schemas.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas'
},
],

Optional fields

services

  • Type: Service[]

List of services to add and what events they publish (sends) and consume (receives)

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
services: [
// Maps exact events to the service
{ id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], receives:[{ detailType: "InventoryAdjusted"}]}] },

// Filter by source (all events that match the source get assigned). This example shows any event matching the source
// "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
{ id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders"}], receives:[{ detailType: "UserCheckedOut"}] },


// This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
]
},
];

Service properties

Property nameRequiredDescription
idrequiredId of the service, this will also be used as the folder name of your service.
versionrequiredThe version of the service
sendsoptionalThe events the service sends (publishes). You can use EventCatalog filters to match your events.
receivesoptionalThe events the service receives (consumes). You can use EventCatalog filters to match your events.

domain

The domain you want the services be associated with in your catalog.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
services: [
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
];

Service properties

Property nameRequiredDescription
idrequiredId of the domain, this will also be used as the folder name of your domain.
versionrequiredThe version of the domain
nameoptionalFriendly name for your domain.

credentials

  • Type: AwsCredentialIdentity | AwsCredentialIdentityProvider

AWS credentials to use for your plugin.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
credentials: {
accessKeyId: 'ACCESS_KEY',
secretAccessKey: 'ACCESS_KEY',
accountId: 'ACCOUNT_ID',
},
services: [
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
]
},
];

If you are using credentials you will want to create a user with limited permissions. See the documentation to get started.

domain

The domain you want the services be associated with in your catalog.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
services: [
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
];

eventBusName

The name of the event bus the events belong too.

A EventCatalog badge is added to your events when they generate with the event bus name.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
eventBusName: 'payment-bus',
services: [
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
];

mapEventsBy

When events are mapped to EventCatalog they are mapped by detailType by default. This means a schema with the name orders.app@OrderPlaced would be mapped to EventCatalog as OrderPlaced.

You can override this by setting the mapEventsBy field in your generator configuration.

Setting mapEventsBy to schema-name will map the event to EventCatalog by it's schema name, in this example it would map the event to orders.app@OrderPlaced.

eventcatalog.config.js
[
'@eventcatalog/generator-eventbridge',
{
region: 'us-east-1',
registryName: 'discovered-schemas',
eventBusName: 'payment-bus',
services: [
{ id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
// Will now map by the schema name itself
mapEventsBy: 'schema-name'
},
];
Property nameRequiredOptionsDescription
mapEventsByoptional (default 'detail-type')detail-type, schema-nameSpecify how you want events to map to EventCatalog from the EventBridge registry. By default the detailType is used of your event, setting the value to schema-name uses the schema name (source@detailType).