Notifications
As an Administrator, you can use notifications to send e-mail or text messages to ThingWorx users based on an event.
Notifications are made up of one or more triggers. A trigger defines which users get notified for specified events and what message they receive. When creating a trigger, you must define the following:
• Source — The source entity and the event that causes the notification to be sent.
• Handler — An entity that provides services to send notification messages. The handler defines the type of content it can send. You can use the following handlers:
◦ MailServer — Thing from the Mail extension (version 3.5.0 and higher of the extension).
Its messages include a subject and body.
◦ Twilio — Thing from the Twilio extension (version 3.1.0 and higher of the extension).
Its messages include a body.
You can download these extensions from the PTC Support site.
 |
A notification cannot have more than one trigger using the same handler entity. If you have more than one trigger using the same handler, you must create another notification entity.
|
• Content — The message sent to the user. The content can include additional data from the event that triggered the notification, including from the event data packet defined in its Data Shape (see Thing Events). You can include event data by using the double square brackets and colons notation. For example, [[:<event_data>:]] where event_data refers to the name of the event parameter. This is the same name that is used when adding a subscription to the event (see Thing Subscriptions).
To find available event parameters, do the following:
1. From Composer, browse > , or Thing Templates or Thing Shapes, and then open an entity.
2. In the Subscriptions area, to add a temporary subscription, click the Add button.
3. Click the Inputs area, and then select an Event from the drop-down list.
4. Optionally, you can select a property from the drop-down list.
A list of inputs appear.
5. To add a parameter to the script area, click the arrow (
) icon.
) icon.The parameter name that appears in the script area can be used in the notification content.
6. Click Done.
The best practice for notification content is to internationalize the text by creating tokens in the default localization table and defining the text there. You can define the notification content by specifying the localization token name in double square brackets, as in [[<token_name>]].
| | There may be limitations on what can be sent, depending on the handler implementation and the end service used to send messages. For example, there may be size limitations on the length of the body of an email sent by a particular mail server. Twilio has a character limit for SMS messages. For more information, see the documentation provided by the messaging service to ensure compliance with such content limitations. |
• Recipients — One or more ThingWorx users to whom the notification message is to be sent.
| | The users must have a valid e-mail address (emailAddress property) and/or mobile phone number (mobilePhone property) specified in their User Extensions configuration (UserExtensions Thing Shape), so they can successfully receive emails and/or text messages. Text messages are sent to the specified mobile phone number and not the SMS address (smsAddress property). |
Notification Events
When notifications are triggered, the following events occur:
• NotificationSent
• NotificationFailed
To subscribe to these events so you can respond to them (for example, to write an entry to a stream or log file), do the following:
1. From Composer, browse > , and then select a notification Thing.
2. Click the Inputs tab and select the NotificationSent or NotificationFailed event as an input to the subscription.
3. Enter the subscription logic.
For more information, see Thing Subscriptions.
Importing or Exporting Notifications
Notifications are exported to one file that contains basic notification information and related trigger information (for example, NotificationDefinition_<name>.xml).
Alternatively, you can export all system entities in Composer from > > > or from > > . This exports notifications and triggers to their own files under the NotificationDefinitions and NotificationContents folders of the specified repository. Triggers cannot be exported by specifying a model tag or project name.
Following are the prerequisites for importing notifications:
• Make sure that the source entity and event exist.
• Handler entities (MailServer Thing or Twilio Thing) should exist.
• User entities specified as recipients exist.
For more information, refer to the topic Adding Notifications.