Events
Within Designer, an event is an object that defines the properties that describe and categorize actual event instances. You create events in Designer to define the messages that applications publish for every instance of an event as it happens in real-time. Each event in Designer defines an event type that represents event instances produced in an EDA. An event instance is a single occurrence of an event message that is produced.
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
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:
- description
- whether the event can be shared to be used by apps in other application domains and by event APIs
- display name, number, and state for each version
- broker type
- topic addresses
- schema
- any custom attributes that have been set up in your organization
To create an event in Designer, perform these steps:
- On the Application Domains page, select the application domain where you want to create the event and click Open Application Domain.
-
Select the Events tab then click Create Event.
- Enter a Name for the event.
- 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.
- (Optional) Add values for any event custom attributes that have been set up in your organization.
- In the Version field, specify a semantic version value for the event in the format major.minor.patch. The default is 0.1.0.
- (Optional) Enter a Version Name for the initial version of the event.
- (Optional) Enter a Description for the event. The Description field supports Markdown. Click toggle preview
to preview the rendered text.
- Select the Broker Type for the event. You can select Kafka only if the account has a Kafka delimiter set. 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.
- Enter a Topic Address. The topic address field displays suggestions based on the 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.
- To specify a schema for the event, click Manage Schemas.
- Select whether the event has a Complex or Primitive schema. Primitive schemas specify a single data type. You define complex schemas in Designer. For more information, see Creating a Schema.
- If you selected a Complex schema, perform these steps:
- Locate the schema you want to reference and click the Name of the schema. The 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.
- Click Select next to the schema version that you want to reference.
- If you selected a Primitive schema, select the data type from the list and click Select Primitive.
- (Optional) Add values for any event version custom attributes that have been set up in your organization.
- Click Save Event.
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:
- On the Application Domains page, select the application domain that contains the event you want to update and click Open Application Domain.
- Select the Events tab.
- In the list of events, click More Actions
for the event that you want to update and select Open Event.
- Perform one of the following actions:
- In the Versions list, click More Actions
for 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 Actions
for 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 Add
to 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.
- Update the event version as necessary.
- 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 an Event Portal Manager or Administrator role 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:
- On the Application Domains page, select the application domain that contains the event you want to update and click Open Application Domain.
- Select the Events tab.
- In the list of events, click More Actions
for the event that you want to update and select Open Event.
- Select the version that you want to change the state of then click Change State.
- 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.
You must add a Kafka event version to a Kafka modeled event mesh. The modeled event mesh must already have an event broker added.
To add a Kafka event version directly to a n environment, perform these steps:
- On the Application Domains page, click the application domain that contains the event and click Open Application Domain.
- Select the Events tab.
- Select the event.
- In the Versions list, select the version that you want to add to an environment
- In the Event Details pane, click More Actions
next to the version that you want to add to an environment, then select Add to Environment.
- Select the Environment that contains the modeled event mesh that you want to add the event version to.
-
Select a modeled event mesh from the Modeled Event Mesh list. You can only select Kafka modeled event meshes.
- Select the Event Broker. Kafka modeled event meshes can have only one event broker.
- Click Add.
After you add the event version, you can view it in the modeled event mesh in Runtime Event Manager.