Symphony Messaging Dev Docs
Developer CertificationREST API
  • Start Your Developer Journey
  • Bots
    • Building Bots
    • Planning Your Bot
      • Conversational Bot
      • Interactive Bot
      • Headless Bot
    • Getting Started
      • Getting Started with BDK
      • Creating a Service Account
      • Configuration
      • Truststores
    • Overview of REST API
      • REST API Architecture
      • Overview of Pod API
      • Overview of Key Manager API
      • Overview of Agent API
      • Bot Permissions
      • REST API Reference
    • Authentication
      • RSA Authentication Workflow
      • Certificate Authentication Workflow
    • Datafeed
      • Real-Time Events
      • Overview of Streams
    • Messages
      • MessageML
        • MessageML Basics
          • Content Grouping
          • Text formatting and semantics
          • Tables
          • Images
          • Tags and mentions
            • Enhanced tags notice
          • Style Attributes
          • Special Characters
          • Emojis
        • Elements Interactive Forms
          • Buttons
            • Icon set for Buttons
          • Text Field
          • Masked Text Field
          • Text Area
          • Checkbox
          • Radio Button
          • Dropdown Menu
          • Person Selector
          • Room Selector
          • Date Picker
          • Time Picker
          • Timezone Picker
          • Table Select
          • Regular Expressions - Regex
        • Extensibility UI Actions
          • OpenChat
          • Dialog
        • Entities
          • Standard Entities
          • Custom Entities
      • PresentationML
    • Bots Best Practices
    • Open Source Code Samples
  • Extension Apps
    • Building Extension Apps
    • Planning Your App
    • Getting Started
      • Getting Started with ADK
      • Application Manifest Bundle
      • Add an Extension App to a Symphony Pod
    • Overview of Extension API
      • Initialization
      • Register and Connect
      • Extension API Services
        • Service Interface
        • Register and Subscribe
        • Modules Service
        • Entity Service
          • Entity Advanced Templating
          • Message Format - ExtensionML
        • Applications-Nav Service
        • Share Service
        • Commerce Service
        • Dialogs Service
        • UI Service
          • Receiving Conversation and User Information
          • Filter Function
    • App Authentication
      • Circle of Trust Authentication
      • OBO Authentication
  • Developer Tools
    • Symphony Messaging Generator
    • Bot Developer Kit for Java
      • Build a Conversational Bot
      • Build an Interactive Bot
      • Build a Headless Bot
      • Integrate a Bot with an Identity Provider
    • Bot Developer Kit for Python
    • App Developer Kit
      • Build a Basic Extension App
      • Build an Extension App with App Views
        • Add Buttons and Handlers to an Extension App
        • Add BDK to an Extension App for Circle of Trust
      • Build an Extension App with Message Renderers
    • Postman
    • UI Style Guide
      • Colors
      • Form Elements
      • Buttons
  • Embedded Modules
    • Symphony Messaging URI
      • Symphony Messaging URI for Mobile (deprecated)
    • Desktop interoperability
      • FDC3 intents
        • Message format
      • Configuration guide
        • Configure Interop.io
        • Configure Here Core
        • Configure Finsemble
        • Configure with Embedded Mode
        • Troubleshooting
      • Change log
    • Embedded Mode
      • Get started
      • Configuration parameters
      • Open a chat
      • Send a message
      • Create a room
      • Pin a message
      • Notifications
      • Support for extension applications
      • Open an app
      • Embedded Mode with Sponsored Access
      • Pricing tiers
      • Logout
    • Universal Webhook
      • User guide
        • Example with Splunk
      • Installation guide
  • Symphony REST API
    • Messaging REST API
    • Federation
    • Sponsored Access API
    • Enhanced Directory API
  • Developer Certification
    • Developer Certification
  • Mobile Frameworks
    • Blackberry
    • MobileIron
  • Admin Guides
    • Change Logs
      • API Agent
        • Agent - 25.5
        • Agent - 25.3 (LTS)
        • Agent - 24.12 (LTS)
        • Agent - 24.9 (LTS)
        • Agent - 24.6 (LTS)
        • Archives
          • Agent - 24.11
          • Agent - 24.10
          • Agent - 23.9 (LTS)
          • Agent - 24.8
          • Agent - 24.3 (LTS)
          • Agent - 24.2
          • Agent - 24.1
          • Agent - 23.12 (LTS)
          • Agent - 23.11
          • Agent - 23.10
          • Agent - 23.7
          • Agent - 23.6 (LTS)
          • Agent - 23.4
          • Agent - 23.3 (LTS)
          • Agent - 23.1
          • Agent - 22.12 (LTS)
          • Agent - 22.11
          • Agent - 22.10
          • Agent - 22.9 (LTS)
          • Agent - 22.8
          • Agent - 22.7
          • Agent - 22.6 (LTS)
          • Agent - 20.14
          • Agent - 20.13
          • Agent - 20.12
          • Agent - 20.10
          • Agent - 20.9 (2.62)
          • Agent - 20.7 (2.61)
          • Agent - 20.6 (2.60)
          • Agent - 20.5 (2.59)
          • Agent - 20.4 (2.58)
      • SBE (Pod API)
        • SBE - 24.1
        • SBE - 20.16
        • SBE - 20.15
        • Archives
          • SBE - 20.14
          • SBE - 20.13
          • SBE - 20.12
          • SBE - 20.10
          • SBE - 20.9 (1.62)
          • SBE - 20.7 (1.61)
          • SBE - 20.6 (1.60)
          • SBE - 20.5 (1.59)
          • SBE - 20.4 (1.58)
      • Client 2.0 APIs
        • Client 2.0 - 25.05
        • Client 2.0 - 25.03
        • Client 2.0 - 24.12
        • Client 2.0 - 24.05
        • Client 2.0 - 23.02
        • Client 2.0 - 22.11
        • Archives
          • Client 2.0 - 20.4
          • Client 2.0 - 20.5
          • Client 2.0 - 20.6
          • Client 2.0 - 20.7
          • Client 2.0 - 20.9
          • Client 2.0 - 20.10
          • Client 2.0 - 20.12
          • Client 2.0 - 22.8
          • Client 2.0 - 22.10
      • Universal Webhook
        • Univ Webhook - 2.6
        • Univ Webhook - 2.4
        • Univ Webhook - 2.2
        • Univ Webhook - 2.1
        • Univ Webhook - 2.0
    • API Change Management
    • Global Throttling
    • Agent Guide
      • Network Topology
      • Agent Download
      • Agent Installation
      • Agent Configuration Fields
      • Agent Server High Availability
      • Agent Performance Tuning
Powered by GitBook
On this page
  • Definition
  • Prerequisites
  • Sending Structured Objects in Messages
  • Message and Object Presentation
  • Reading objects
  • Renderer Applications
  • Go further...

Was this helpful?

Export as PDF
  1. Bots
  2. Messages
  3. MessageML
  4. Entities

Custom Entities

Last updated 1 year ago

Was this helpful?

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 .

Prerequisites

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.

Sending Structured Objects in Messages

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

  • 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.

  • 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.

Message and Object Presentation

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

<messageML>
  Hello <mention email="user@music.org" />. Here is an important message
</messageML>

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

<messageML>
  Hello <mention email="user@music.org" />. Here is an important message with an
  <div class="entity" data-entity-id="object001" /> 
  included.
</messageML>

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.

{
    "object001":
    {
        "type":     "org.symphonyoss.fin.security",
        "version":  "1.0",
        "id":
        [
            {
                "type":     "org.symphonyoss.fin.security.id.ticker",
                "value":    "IBM"
            },
            {
                "type":     "org.symphonyoss.fin.security.id.isin",
                "value":    "US0378331005"
            },
            {
                "type":     "org.symphonyoss.fin.security.id.cusip",
                "value":    "037833100"
            }
        ]
    }
}

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

<messageML>
  Hello <mention email="user@music.org" />. Here is an important message with an 
  <div class="entity" data-entity-id="object001">object</div> 
  included.
</messageML>

Reading objects

Note:

Renderer Applications

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

Go further...

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

Object Presentation, in format.

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

These parameters also support using with Structured Objects.

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.

As described in , messages with can be created using the shorthand tags or the full tags. When they are read, the message presentation always contain the full tags, which are a subset of HTML tags.

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 .

Render the object itself, by implementing the .

Symphony's Extension API
MessageML v2
Create Message
Apache FreeMarker templates
Read Message
Message Format - MessageML v2
Structured Objects
Extension application
entity service
registerRenderer function
render function