Enumerations

In Designer, enumerations are a type of topic address level variable that define a bounded list of acceptable values for a variable. If you use enumerations to define variables in topic domains and topic addresses, the values you add should include all potential values related to one element of data for the event. For example, if an event instance could occur in any of six possible locations and you want the topic to include the location, you could create an enumeration that has values for all six options. For more information, see Defining Topic Addresses for Events. You must have the Administrator or Event Portal Manager role to create or edit enumerations. Kafka topic addresses don't support enumerations.

This section includes the following tasks:

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

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

Creating an Enumeration

When you create an enumeration don't use /, *, >, or ! characters in the name of the enumeration or in values within the enumeration. These characters have special meaning and can't be used in topic addresses.

To create an enumeration in Designer, perform these steps:

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, select Designer.
  3. On the Application Domains page, click the application domain that you want to add the enumeration to.
  4. Click Components to switch to the list view.

  5. Select the Enumerations tab and then click Create Enumeration.

    Screenshot showing the settings described in the surrounding steps.

  6. Enter a Name for the enumeration.
  7. If you want the enumeration to be available to shared events and events in other application domains, select Allow Enumeration to be shared across application domains.
  8. In the Version field, specify a semantic version value for the enumeration in the format major.minor.patch. The default is 0.1.0.
  9. (Optional) Enter a Version Name for the initial version of the enumeration.
  10. (Optional) Enter a Description for the enumeration. The Description field supports Markdown. Click toggle preview to preview the rendered text.
  11. In the Value Set area, enter values for the enumeration using one of the following methods:
    • Enter a value in the top Value field and optionally, add a Description. When you add a value to the Value field, new Value and Description fields appear below the current fields to let you add additional values.
    • Click Upload From File to upload a JSON file with a value set in the format:
      [{ "value": "Monday", "description": "Start of the work week." }]

  12. (Optional) Drag the rows up or down the Value Set list to reorder the values.
  13. (Optional) Add values for any custom attributes that have been set up in your organization.
  14. Click Save Enumeration.

Updating an Enumeration

When you update an enumeration, you can update an existing version or create a new version of the enumeration. Versions allow you to work on updates and test new versions in a 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 the 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, the reference does not update automatically. You can choose when to update references to the new version.

To update an enumeration, perform these steps:

  1. On the Application Domains page, click the application domain that contains the enumeration you want to update.
  2. Click Components to switch to the list view.
  3. Select the Enumerations tab.
  4. In the list of enumerations, click More Actions for the enumeration you that want to update and select Open Enumeration.
  5. 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 enumeration. You can edit an enumeration 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 Addto create a new version of the enumeration without duplicating an existing version. By default, the new version number is the next unused major version. You can change the new version number to any number not already in use.
  6. Update the enumeration version as necessary.
  7. Click Save Version or Save & Close.

Changing the State of an Enumeration Version

When you create a new version of an enumeration, 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 enumeration, you may also want to change older versions of the enumeration 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 must change enumerations out of Draft state before you can change any events that reference them out of Draft state. If you want to retire an enumeration version, you must first retire all event versions that reference it.

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

  1. On the Application Domains page, click the application domain that contains the enumeration you want to update.
  2. Click Components to switch to the list view.
  3. Select the Enumerations tab.
  4. In the list of enumerations, click More Actions for the enumeration that you want to update and select Open Enumeration.
  5. Select the version that you want to change the state of, then click Manage Lifecycle.
  6. Select the new state.
  7. (Optional) If you set the State to Deprecated or Retired, set the End of Life date. If you set a planned or actual End of Life date, the date displays in the version details.
  8. Click Save.