Tachyon event management cmdlets
Cmdlets used to manage Tachyon events and subscriptions.
Tachyon events are an important feature first introduced in Tachyon 5.0. However, API support for event management was not added until release 5.1. To use these cmdlets therefore, your Tachyon installation must be at release 5.1 or later.
About Events
Events are used internally within various subsystems such as Experience. You can also add new events and then raise them in SCALE code. Additionally, the Guaranteed State subsystem can define triggers based on events.
Events are raised at an device during the execution of a Guaranteed State fragment, or within a standard Tachyon instruction, using the RAISE keyword. An event consists of two components.
The Event Topic, which is a string which defines the event. Event topics may contain one or more period characters (.)
For example, an event topic could be 'MyEventTopic.Foo.Bar'
The Event Payload, which is an arbitrary piece of JSON. The event payload allows arbitrary data to be associated with an event.
Event subscriptions
Events which are raised on an device are relayed back to the Tachyon server. Events can cause an action to occur both on the device and at the server.
On the device, a raised event can act directly as the trigger condition for one or more Guaranteed State rules. Additionally, when the event is relayed back to the server, it can cause one or more event subscriptions to be triggered server-side.
An event subscription must be associated with an event subscription assignment in order for any server-side activity to occur as a result of a raised event. Event subscription assignments associate an event subscription with one or more management groups.
Event topics and wildcards
Event subscriptions can specify an individual topic, or they can specify a wildcarded topic. For example, an event subscription can specify MyEventTopic.Foo.Bar, or MyEventTopic.Foo.* or MyEventTopic.*. Each of these subscriptions will include MyEventTopic.Foo.Bar but the wildcards allow an increasingly wide range of topics to be captured by a single event subscription.
Note
You cannot specify a wildcard other than at the end of an event topic. Thus, MyEventTopic.*.Bar is not a valid topic to specify in an event subscription.
If you specify multiple wildcarded topics as in the example above, then the event will be processed for each subscription that matches.
You should not make assumptions about the order in which event subscriptions are processed, or the order in which events themselves are sent and received. If you need to determine event ordering, you should include a mechanism in the event payload, such as a timestamp, to ensure that the receiver can determine their ordering.
Event delivery to the server is made on a 'best effort' basis. Although the platform is designed to process events reliably, you should not assume that event delivery is absolutely guaranteed.
Event devices
An event subscription ultimately causes a specified device to receive the event. This event consumer is responsible for performing any action associated with the event.
Event management cmdlets
The following cmdlets are available to manage event subscriptions and assignments
Note
These cmdlets only work with Tachyon 5.1 and greater, although events were introduced in 5.0. This is because the underlying event management API was not implemented in 5.0
Get-TachyonEventSource
Retrieves all the available event sources. Event sources are associated with the user survey functionality implemented in Tachyon 5.1 and contain ancillary data used by this subsystem.
Get-TachyonEventSubscription [-Id <id>]
Retrieves the event subscriptions which have been defined. Event subscriptions associate a consumer with a topic. For convenience, the consumer offloading target Url is included in the results.
The offloading target URL is the destination to which responses routed to a consumer are sent. A consumer with no offloading target URL receives responses directly back to the Tachyon database.
The Url property (as opposed to the offloading target Url) is specific to each event subscription. It defines the destination to which event data will be sent when an event is raised. An event subscription must have a URL. Unlike consumers themselves, event data cannot be routed directly to the Tachyon database.
If the optional Id parameter is specified, only the event subscription corresponding to that Id is returned.
Add-TachyonEventSubscription -ConsumerName <consumerName> -Topic <topic> -Url <url>
Adds a new event subscription and returns the Id and associated information in the same format as Get-EventSubscriptions -Id
It is possible to add multiple event subscriptions for the same topic and URL. Event subscriptions are not unique by topic and URL.
Remove-TachyonEventSubscription -Id <id>
Removes the event subscription whose Id is defined by the -Id parameter
Warning
Some event subscriptions are used internally by Tachyon subsystems such as Experience. If you remove or alter these, these subsystems may not function correctly. Exercise caution when managing event subscriptions and event subscription assignments to ensure you do not inadvertantly affect Tachyon applications that make use of them.
Event subscriptions may be associated with one or more event subscription assignments (see below). If an event subscription is removed and there are event subscription assignments for that event subscription, these assignments will also be removed.
Get-TachyonEventSubscriptionAssignment [-Topic <topic>]
Gets all event subscription assignments
If the optional -Topic parameter is specified, only those assignments associated with the topic specified are returned.
It is possible to have multiple event subscription assignments for the same topic.
Add-TachyonEventSubscriptionAssignment -SubscriptionId <subscriptionId> -ManagementGroupId <groupId>
Adds a new event subscription assignment. The -SubscriptionId parameter specifies the Id of the event subscription to which this assignment is to be added, and the -ManagementGroupId specifies the management group for which the assignment is effective.
Because event subscriptions are not unique by topic, you must specify the Id of the event subscription for this cmdlet.
Remove-TachyonEventSubscriptionAssignment -Id <id>
Removes the event subscription assignment whose Id is defined by the -Id parameter.
This is not to be confused with the Id of the parent event subscription. This may be associated with zero, one, or many, event subscription assignments, each of which has its own unique Id. You can view the event subscription assignment Ids with the get-TachyonEventSubscriptionAssignments cmdlet.
Warning
Some event subscriptions are used internally by Tachyon subsystems such as Experience. If you remove or alter these, these subsystems may not function correctly. Exercise caution when managing event subscriptions and event subscription assignments to ensure you do not inadvertently affect Tachyon applications that make use of them.