Manage schema

AI-generated summary

Genesys Cloud provides schema management capabilities for external event ingestion through the Resource Center, enabling organizations to define and validate business-specific events from external systems such as purchases, claim updates, CRM events, and booking confirmations. External event schemas function as JSON schema-based blueprints that establish consistent field referencing across platform features. Schema creation requires an API call and must specify a schema name, description, and comprehensive attribute list. Each attribute requires definition of name, description, data type, and required status. The platform supports seven data types: Boolean, Date, Date and Time, Enum (up to 50 choices with display labels), Integer, Number, and String (up to 1,). Organizations can create up to 20 schemas with a maximum of 50 attributes per schema. Access to schema management requires a Genesys Cloud CX 1 license and specific permissions across three Journey categories: externalEventsSchema (Add, Edit, View, Delete), externalEventsConfiguration (Add, Edit, View, Delete), and externalEventsEvent (Add). Schema creation represents the mandatory first step in onboarding external events to the platform. Once saved, schemas enforce strict backwards compatibility with locked structure to prevent conflicts with dependent objects including event configurations and in-flight events. Permitted modifications include adding new attributes, updating descriptions, increasing numeric or text-length limits, and adding options to existing enums. Prohibited modifications include deleting or disabling existing attributes, modifying data types or underlying key names, converting optional attributes to required, or removing enum options. All attribute changes automatically generate new versions, with event configurations always utilizing the latest version. Complete schema deletion or disabling represents the only removal option for schemas; individual attribute removal is not permitted. Disabling or deleting a schema prevents its use in new or updated event configurations, requiring verification that no active configurations depend on the schema before deletion. Users access schema management through Menu > Orchestration > External Event Ingestion > Schemas, where they can view schema lists, search functionality, manage individual schema details including setup, name, description, and attributes, and access action options for schema administration. The interface includes navigation back to the Schema List and feedback mechanisms for documentation improvement

PrerequisitesClick to expand

Genesys Cloud CX 1 license

The following permissions:

Journey > externalEventsSchema – Add
Journey > externalEventsSchema – Edit
Journey > externalEventsSchema – View
Journey > externalEventsSchema – Delete
Journey > externalEventsConfiguration – Add
Journey > externalEventsConfiguration – Edit
Journey > externalEventsConfiguration – View
Journey > externalEventsConfiguration – Delete
Journey > externalEventsEvent – Add

An external event schema is a blueprint that defines the structure of a business-specific event you want to send into Genesys Cloud from a system outside the platform — for example, a purchase, a claim update, an event from a CRM system, or a booking confirmation. A schema defines the event’s attributes and each attribute’s data type so that, when an event arrives, Genesys Cloud can validate it and other features can reference its fields consistently.

Schemas are formulated according to the JSON schema specification and created with an API call, as described in the developer center documentation. Genesys Cloud enforces strict backwards compatibility on schemas once they’re saved, so it’s worth understanding upfront what you can, and can’t, change later.

Schema for external events must be created as the first step in onboarding external events to Genesys Cloud.

The following sections describe how you can work with a schema:

Create a schemaClick to expand

A schema is created through an API call from the Developer Center. A schema has a name and a set of attributes. The schema you create must contain the following items:

Schema Name: Specify a name to the schema.
Description: Specify a description about the schema for reference.
Schema Attributes: Create the attribute list associated to the schema by specifying the following values:
- Name: Specify a name to the attribute.
- Description: Specify a description about the attribute for reference.
- Data Type: Specify the attribute’s data type. The following data types are supported:
  - Boolean (true/false)
  - Date (a calendar date)
  - Date and time
  - Enum (a fixed list of up to 50 choices, each choice has a stored value and a separate business-friendly display label, for example storing “CC” but showing admins “Credit Card”)
  - Integer (a whole number)
  - Number (any numeric value, including decimals)
  - String (text, up to 1,000 characters)
- Required: Specify whether it is a mandatory or optional attribute.

Note: An organization can have up to 20 schemas, and each schema can have up to 50 attributes.

Example schema

The following table shows about a purchaseEvent schema used to send e-commerce purchases into Genesys Cloud:

Attribute (business name)	What it captures	Data Type	Required?
Product ID	The unique identifier of the item that was purchased.	String	Yes
Purchase price	The dollar amount of the purchase.	Number	Yes
Purchase date	The date and time the purchase was completed.	Date and Time	Yes
Payment method	How the customer paid — admins see a credit card, PayPal, or gift card even though the system stores a short code for each.	Enum	No

In the underlying API call, these become fields like attributes.productId, attributes.purchasePrice, and attributes.purchaseDate.

View a schema listClick to expand

View a schemaClick to expand

To view the schema details,

Click Menu > Orchestration > External Event Ingestion > Schemas. The list of schemas created by API calls appear.
From the schema list, do one of the following:
- Navigate to the schema name that you want to view and click the name.
- Under the Actions column, click the vertical dots, and click View from the shortcut menu. The Schema Configuration page appears.
The Schema Configuration page allows you to view the schema details such as schema setup, schema name, description, and schema attributes. After reviewing the schema details, click Go Back to go to the Schema List page.

Edit a schemaClick to expand

After a schema is saved, its structure is locked to prevent issues arising from other objects that use the schema such as event configurations, in-flight events, and anything built on its fields. You can add new attributes, change its description, increase a numeric or text-length limit, and add new options to an existing enum. However, you can’t delete or disable an existing attribute, change its data type or underlying key name, change an optional attribute to require, or remove an enum option once added.

After you change the event attributes, every saved change creates a version automatically; event configurations always use the latest version.

Delete a schemaClick to expand

[NEXT] Was this article helpful?

Get user feedback about articles.