Thing Subscriptions
Subscriptions are services that receive and respond to
events. A subscription has a source, usually a
Thing. A Thing can have a subscription to an event that responds with an action. For example, if an entity fires a
Motor is overheating event, it can subscribe to that event by triggering a
Turn motor off subscription. Things can inherit subscriptions from the
Thing Templates and
Thing Shapes that they use.
A subscription is similar to a standard service, but it is explicitly linked to an event. This allows you to decouple the event from the code that responds to it. Like with a service, you can implement custom business logic to react to the event. You can leverage the capabilities of the model by sending emails through a mail server Thing, writing to a database, or calling any services available in the platform. A subscription does not have an explicit return output as a service does. However, a subscription can call any other service in the model to which the thread security context has access. The thread security context of a subscription is set to the same thread security context of the event that was fired. You can use the same JavaScript editing environment that is used to implement services.
Subscriptions have a defined input, which is the data packet issued by the event and referred to as event data. If the entity subscribes to a defined event, the event data is passed to the subscription function. The event data is described by the event
Data Shape. Within the subscription implementation, the data that is passed from the event acts as the input to the script function. For example, if an entity is subscribed to a Thing property data change event, the subscription script function is called. As a result, the Thing property value, along with other relevant data from the event, are passed to the function as part of the event data.
Many entities can subscribe to the same event. Each entity receives a call to the subscription with the passed event data. An entity can take any action from the subscription script to achieve the solution requirements.
Some advantages of using this technique versus using a service that is called from another service include:
• An event can be subscribed by one or many subscriptions.
• Events are invoked based on system activity, and no user interaction is necessary.
• If more than one Thing is subscribed to an event, you can use a subscription instead of chaining multiple services.
|
Multiple subscriptions to the same event defined on the same Thing, or duplicate subscriptions, are supported in ThingWorx version 8.4.0 and later.
|
|
Event trigger and Subscriptions execute asynchronously. For example, a property update API request receives an immediate response when the property update action completes. It does not wait for the subsequent subscriptions that respond to the Data Change Event to complete.
|
Multiple Subscriptions
Subscriptions have a user-defined name as the unique identifier. Entities can have multiple subscriptions to an event on a Thing. For example, if an entity fires a Motor is overheating event, it can subscribe to that event with both a Turn motor off subscription and a Create Work Order subscription to have a maintenance check of the engine. Any number of other subscriptions can also be created for that event.
If a Thing Template or a Thing Shape implements a subscription to an event, the Things that use that Thing Template or Thing Shape can also create subscriptions to the same event, without requiring a workaround to take additional actions when those events are fired.
Distributed Subscriptions
|
The distributed subscription capability is available in a High Availability only environment from ThingWorx 9.4 and up.
|
Distributed Subscriptions enable the distribution of subscription executions across all ThingWorx nodes when an event triggers many instances of subscriptions. For example, many Things subscribing to the same timer or scheduler event. This enables horizontal scalability of timer/scheduler-based subscription execution across all ThingWorx nodes in High Availability environments for better resource utilization and performance. The Distributed checkbox under the Subscription tab enables this behavior. If the Distributed checkbox is clear, subscriptions to timers and schedulers would be executed in the same node in which the timer or scheduler event is generated. For more information regarding related configuration, see the following: