Custom Entities

Definition

Structured Objects are rich, inline, interactive components of Symphony messages. Objects allow you to build innovative workflows that go beyond working with normal text or attached files.

• Unlike normal message text, these objects are structured and do not need to be parsed to have business logic.

• Unlike attachments, end-users can view and interact with objects directly from their Symphony client, without having to change context.

• Structured Objects can be "injected" into Symphony by sending messages using Symphony's REST API.

• Structured Objects can be rendered richly using .

To inject messages containing structured objects:

• Your pod must be configured for Symphony's REST API, and you must have the Agent, the component used for handling encryption and decryption of messages and content, set up.

• Your Agent must be version 1.51 or later.

• You must have an X.509 identity certificate for your bot service user for REST API authentication, where the common name on the certificate matches your service user's username.

To build renderer applications for displaying your structured object:

• You need to have an extension application created and enabled on your pod.

Structured Objects are placed into Symphony messages and have two components:

• Object Presentation, in format.

• Object Data, a JSON object.

Any message in Symphony can contain zero or more Structured Objects.

• A message will always contain message presentation, in MessageML v2 format, with the optional object presentation of the Structured Objects it may contain.

• If the message contains any structured objects, it will contain JSON data with all object data of the structured objects it may contain.

You can create an object by invoking the endpoint. You need to include:

• The message parameter, which contains the message presentation, with the object presentation for each Structured Object.

• The data parameter, which contains JSON data with the object presentation for each structured object.

These parameters also support using with Structured Objects.

Message presentation is represented in MessageML format. For example:HTML

To add an object to a message, include a div or a span tag with a unique data-entity-id attribute:HTML

The data-entity-id tag refers to a specific object in the JSON data, which needs to include:

• The data type.

• The data version of that type. Both are needed to build renderer applications which can render this type of that version.

This data can be used by applications in the web client to provide a rich display or end-user interactivity. In case no specific renderer application is available, you must provide a default presentation in the div or a span tags.HTML

You can read objects using any of the endpoints designed to read messages, for example, the endpoint. This endpoint will let you read both the message presentation and object data fields.

Renderer Applications leverage the Extension API to dynamically replace the presentation of a structured object. To create a renderer application:

• Create an

• Your application needs to use the , which will allow you to:

  • Register your application as being able to render a specific type, using the .

To learn more about building Extension Applications that leverage structured objects, continue here: