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'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted"}, eventBusName: 'inventory'] },

          // 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'
  },
],

`licenseKey`

Type: String

The license key for the EventBridge generator. You can get a 14 day trial license key to try the plugin out by going to EventCatalog Cloud.

eventcatalog.config.js
[
  '@eventcatalog/generator-eventbridge',
  {
    licenseKey: 'YOUR_LICENSE_KEY'
  },
],

Using environment variables

You can also set the license key as an environment variable. If this is set on the machine the licenseKey is not required in the generator configuration.

EVENTCATALOG_LICENSE_KEY_EVENTBRIDGE=YOUR_LICENSE_KEY

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 name	Required	Description
id	required	Id of the service, this will also be used as the folder name of your service.
version	required	The version of the service
sends	optional	The events the service sends (publishes). You can use EventCatalog filters to match your events.
sends.eventBusName	optional	The name of the EventBus for the matched events. This will be displayed as an EventCatalog Channel.
receives	optional	The events the service receives (consumes). You can use EventCatalog filters to match your events.
receives.eventBusName	optional	The name of the EventBus for the matched events. This will be displayed as an EventCatalog Channel.

`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 name	Required	Description
id	required	Id of the domain, this will also be used as the folder name of your domain.
version	required	The version of the domain
name	optional	Friendly name for your domain.

`writeFilesToRoot`

Added in @eventcatalog/generator-eventbridge@2.0.0

Type: Boolean

By default your EventBridge events will be written to the service folder (if you define one). This helps keep related events together in your EventCatalog folder structure.

Example:

services/
  payment-service/
    index.mdx
    events/
      payment-created/
        index.mdx
      payment-updated/
        index.mdx

If you set writeFilesToRoot to true, your EventBridge events will be written to the root of your catalog (pre v2.0.0 behavior).

Example:

services/
  payment-service/
    index.mdx
events/
  payment-created/
    index.mdx
  payment-updated/
    index.mdx

`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`

Added in @eventcatalog/generator-eventbridge@1.0.0

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 name	Required	Options	Description
mapEventsBy	optional (default 'detail-type')	`detail-type`, `schema-name`	Specify 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).

Overview​

Required fields​

region​

registryName​

licenseKey​

Optional fields​

services​

domain​

writeFilesToRoot​

credentials​

domain​

eventBusName​

mapEventsBy​

Overview

Required fields

`region`

`registryName`

`licenseKey`

Optional fields

`services`

`domain`

`writeFilesToRoot`

`credentials`

`domain`

`eventBusName`

`mapEventsBy`