Events

Within Event Portal, an event is an object that defines the properties that describe and categorize actual event instances. Each event in Designer defines an event type that represents event instances produced in an event-driven architecture (EDA). An event instance is a single occurrence of an event message that is produced.

You can create events in Designer and you can add events to Designer by importing Kafka topics from your runtime data in Runtime Event Manager. For more information, see Importing Kafka Objects.

This section includes the following tasks:

• Creating an Event
• Updating an Event
• Changing the State of an Event Version
• Adding an Event to an Environment

You can also create custom attributes for events. For more information, see Using Custom Attributes

You can also move events to a different application domain. For more information, see Moving Objects Between Application Domains.

Creating an Event

You can create an event in any application domain where you have sufficient access based on your role. When you create an event, you specify several settings:

• name
• broker type (Solace or Kafka)
• whether the event can be shared to be used by applications in other application domains and by event APIs
• version description, display name, number, and state
• topic addresses
• schemas
• any custom attributes that have been set up in your organization

To create an event in Designer, perform these steps:

1. On the Application Domains page, click the application domain that you want add the event to.
2. Click Components to switch to the list view.

3. Select the Events tab then click Create Event.

   

4. Enter a Name for the event.
5. Select the Broker Type for the event. All versions of the event have the same broker type.

   You can select Kafka only if a Kafka delimiter is set for the account. If no Kafka delimiter is set, click Kafka Settings to set the delimiter or, if you don't have the required access level, contact an administrator.

6. If you want the event to be available to applications in other application domains and to event APIs, select Allow event to be shared across application domains.
7. (Optional) Add values for any event custom attributes that have been set up in your organization.
8. In the Version field, specify the semantic version value for the first version of the event in the format major.minor.patch. The default is 0.1.0.
9. (Optional) Enter a Version Name for the first version of the event.
10. (Optional) Enter a version description. The Description field supports Markdown. Click toggle preview to preview the rendered text.
11. Enter a Topic Address. The topic address field displays suggestions based on the broker type, topic domain and existing topic addresses for other events in the application domain. The address must meet the following conditions. For more information, see Topic Addresses.
    • If required by the application domain, the topic address must be unique within the application domain.
    • If required by the application domain, the topic address must begin with a topic domain. You can select from existing topic domains to start the topic address.
    • For Solace topic addresses, don't use the *, >, or ! characters in a topic address.
    • To include a variable, surround it with braces { }.

    • To use an enumeration as a variable, type the opening brace {, click Configure Variable, and select an enumeration and version.

      

      Enumerations are supported only in Solace topic addresses. If the event is shared, you can select only a shared enumeration.

12. (Optional) Click Select Schema for a Solace event , or for the Value or Key schema in a Kafka event and perform these steps:
    1. Select whether the schema is Complex or Primitive. Primitive schemas specify a single data type within the event. Complex schemas are separate objects in Designer. For more information, see Schemas.
    2. If you selected a Complex schema, click Select next to the schema version that you want to reference. The schema list shows schemas in the same application domain and shared schemas from other application domains that you have access to. You can filter the list by application domain. If you selected Allow Event to be shared across application domains, only shared schemas appear in the list.
    3. If you selected a Primitive schema, select the data type from the list and click Select Primitive.
13. (Optional) Add values for any event version custom attributes that have been set up in your organization.
14. Click Save Event.

Considerations for Creating and Updating Kafka Events

In Kafka EDAs, an event represents a unique relationship between a topic and a schema. An event can't have multiple topic addresses or reference different value schemas across its versions. Designer has additional validation restrictions for Kafka events to ensure your designs accurately represent your Kafka clusters. In addition to requiring all versions of an event to have the same broker type, Designer enforces these restrictions for events with Kafka broker types:

• All versions of a Kafka event must have the same topic address.

• Kafka brokers don't recognize level delimiters in topics. You can specify a delimiter that Event Portal recognizes in Kafka topics. All Kafka topic addresses in your organization's account must use the same delimiter.

• Kafka topic addresses don't support enumerations or wildcards.

• You can't create a second version of a Kafka event unless you've set a topic address for the first version.

• If more than one version of a Kafka event exists, you can't change the topic address.

• All versions of a Kafka event must reference the same schema object for the Value schema, and each event version must reference a different version of that schema object

• Two separate Kafka events in Designer can have the same topic address but if the topic addresses for two event match, they can't both reference the same schema for the value schema.

Updating an Event

When you update an event, you can update an existing version or create a new version of the event. Versions allow you to work on updates and test new versions in development and staging environments while the latest stable version remains in the production environment. Each version also has a lifecycle state. You can only edit versions that are in Draft state. For more information, see Object Versions and Lifecycle States.

The version number uses semantic versioning in the format major.minor.patch. When you update an object, you have three options:

• If the object version is in Draft state, you can update an existing version and retain the version number

• If the object version is in Released, Deprecated, or Retired state, you can duplicate a version and increment the version number to create a new Draft version.

• If the object version is in Released, Deprecated, or Retired state, you can create a new version of the object from scratch

If you want to update a version that is not in Draft state it is best practice to create a new version rather than returning the version to Draft state.

When you reference an object, for example, you specify the schema that an event uses or an event that an application publishes, you select the version of the object that you want to reference. If a new version of a referenced object is created, you can choose when to update references to the new version.

To update an event, perform these steps:

1. On the Application Domains page,click the application domain that contains the event you want to update.
2. Click Components to switch to the list view.
3. Select the Events tab.
4. In the list of events, click More Actionsfor the event that you want to update and select Open Event.
5. Perform one of the following actions:
• In the Versions list, click More Actionsfor the version that you want to update and select Edit. Any changes you make update that version of the event. You can edit an event version only if it is in Draft state.
• In the Versions list, click More Actionsfor the version that you want to update and select Duplicate. All properties of the existing version are copied into a new version. By default, the new version number is incremented by 0.0.1. You can change the version number to any number not already in use.
• Above the Versions list, click Addto create a new version of the event without duplicating an existing version. By default, the new version number is the next unused major version. You can change the version number to any number not already in use.
6. Update the event version as necessary.
7. Click Save Version or Save & Close.

Changing the State of an Event Version

When you create a new version of an event, the version is in Draft state. When the version is ready, you can change the version state to Released. When you release a new version of an event, you may also want to change older versions of the event to Deprecated or Retired. You must have at least the Event Portal User role with Manager level access to the application domain to change the version state. For more information, see Object Versions and Lifecycle States

You can only change an event version from Draft to Released state after the schema and any enumerations that the event references have been changed out of Draft state. If you want to retire an event version, you must first retire all application and event API versions that reference it.

To change the state of an event version, perform these steps:

1. On the Application Domains page,click the application domain that contains the event you want to update.
2. Click Components to switch to the list view.
3. Select the Events tab.
4. In the list of events, click More Actionsfor the event that you want to update and select Open Event.
5. Select the version that you want to change the state of then click Change State.
6. Select the new state and click Change State.

Adding an Event to an Environment

How you add event versions from Designer to an environment depends on the event type. To add a Solace event version to an environment, you add an application that publishes the event. For more information, see: Adding an Application to an Environment. You can add a Kafka event version in the same way or by adding it directly to an environment. If you add a Kafka event directly, you associate a version of the event with a model event broker in a Kafka modeled event mesh.

When you import a Kafka event into Event Portal using Runtime Event Manager, you select the environment, modeled event mesh, and event broker. You can add the imported event to additional environments from Designer.

To add a Kafka event version to a modeled event mesh within an environment, perform these steps:

1. On the Application Domains page,click the application domain that contains the event.
2. Click Components to switch to list view.
3. Select the Events tab.
4. Select the event.
5. In the Versions list, select the version that you want to add to an environment.
6. In the Event Details pane, click More Actionsnext to the version that you want to add to an environment, then select Add to Environment.
7. Select the Environment that contains the modeled event mesh that you want to add the event version to.
8. Select a modeled event mesh from the Modeled Event Mesh list. You can only select Kafka modeled event meshes.

9. Select the Event Broker. Kafka modeled event meshes can have only one event broker.

   

10. Click Add.

After you add the event version, you can view it in the modeled event mesh in Runtime Event Manager.