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