Declare App Topics and Payloads
You declare the topics that a custom app publishes or subscribes to in the App Specification in the <topics> section. Topics allow apps to participate in loosely-coupled interactions that users can define in Mashboard.
The basic syntax requirements for declaring topics is discussed in
<topics> or <topic>. How you define topic names, datatypes and specify topic payloads, however, impacts how app interactions can be configured.
Topic Name
Topic names must be valid JavaScript names and must be unique for a given app.
Tip: | It is a best practice to use topic names with two parts (or tokens), in the form namespace.event. Use the same namespace as your custom app and an event name or type, such as MyApp.selectProject. This helps ensure that topic names are unique and clear to users when they wire them to other apps in Mashboard. |
It is better to limit topic names to characters, numbers and the simplest of punctuation or other symbols. Two symbols have a specific meaning for topic names:
Asterisk (*) cannot be used in a topic name as this character is used as a wildcard character for topic subscriptions.
Period (.) is used to separate tokens within a topic name. Wildcards can replace tokens to define the set of topics for a subscription.
Simple Topic Payloads
Topics have a datatype that defines what messages for that topic are expected to contain. For simple datatypes, such as string, the message is just a single, simple value with no additional properties. For example:]
<topics>
<topic name="sample.number" publish="true" datatype="number"/>
<topic name="sample.string" subscribe="true" datatype="string"/>
</topics>
Complex Topic Payloads: Object
The default datatype for topics is
object which is used for messages that are complex objects containing several properties. With the
object datatype, you specify the expected properties using <properties> and <property> within <topic>.
App properties must each be simple types. For topics, however, properties can be complex, containing properties down to any level needed. Properties in message payloads can be arrays, however, you cannot specify that a property in a topic payload is an array in the App Specification.
For example:
The messages that an app publishes may contain properties other than those specified in the topic payload. Any properties not defined in the payload are not available for wiring in Mashboard. They are also not available to the subscriber app at runtime, unless the subscriber topic uses the any datatype.
Open Topic Payloads: Any
Apps can leave message payloads open by using the any datatype for a topic. Open topic payloads can be useful when an app is designed to work with a variety of apps that use a common information source, such as a database or a specific system in your organization (CRM, ERP or others). Topics from a common information source typically use a well-known set of data with a common set of names that an open subscription can use reliably.
For example:
<topics>
<topic name="publish.any" publish="true" datatype="any"/>
<topic name="subscribe.any" subscribe="true" datatype="any"/>
</topics>
Topics with a datatype of any for publisher apps can be wired in Mashboard to subscribers at the topic level. If users trigger the event that publishes a message in Mashboard, they can also wire the published message payload to the subscriber payload.
Topics with a datatype of any for subscriber apps indicate that the Wiring Manager should pass the published topic on to the subscriber as-is, with no changes. You can wire a publisher topic to an open subscriber topic at the topic name level, but no wiring is possible for individual properties.
Because of this, subscription handlers for topics with a data type of
any must find message properties and handle validation and mapping themselves. For an example, see
Subscriber App for Loosely-Coupled Interactions.
