Event management cmdlets

Event management cmdlets are used to manage 1E Platform events and subscriptions.

About events

Events are used internally within various subsystems, such as Experience Analytics. You can also add new events and then raise them in SCALE code. Additionally, the Endpoint Automation subsystem can define triggers based on events.

Events are raised at a device during the execution of a Endpoint Automation fragment or within a standard platform instruction, using the RAISE keyword. An event consists of two components:-

Event Topic: A string that defines the event. Event topics may contain one or more period characters (.). For example, an event topic could be MyEventTopic.Foo.Bar.
Event Payload: An arbitrary piece of JSON. The event payload allows arbitrary data to be associated with an event.

Event subscriptions

Events that are raised on a device are relayed back to the 1E key vault 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 Endpoint Automation 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.

At present, the management group assignment doesn't have any practical effect on what the event causes to happen. It's just something that events got hung on to.

Event subscription sources

An event subscription can optionally be associated with an event subscription source. These have two members:

Type string: A free-format text value.
Source parameter: It must be valid JSON.

Sources are used by the Experience Analytics Sentiment Survey functionality but otherwise are available as a general mechanism for parametrizing event subscriptions. Endpoints can retrieve this information as part of the policy history from one of the platform Activity Record tables.

This is done by querying the Policy.PolicyHistory table, for example, SELECT * FROM [Policy.PolicyHistory]. However, note that this table is not emulated within the TIMS development environment. It can only be queried when an actual instruction is run on an endpoint.

Topics and wildcards

Event subscriptions can specify an individual topic or 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.

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.

Don't confuse the use of the term consumer here with the consumer parameter that you specify when you create event subscriptions (as shown below). The consumer parameter corresponds to a configured consumer inside the 1E Platform. Although event subscriptions specify a platform consumer, the eventing subsystem doesn't currently interact with the consumer in any way. This may change in a future platform release.

Event management cmdlets

The following cmdlets are available to manage event subscriptions and assignments.

Get-1EEventSource [ -Id <Id> ]

This cmdlet retrieves all the available event sources or the event source associated with the specified Id. Event sources are associated with the user survey functionality implemented in platform release 5.1 and later, and contain ancillary data used by this subsystem.

Add-1EEventSource -Type <type> -Source <source> | -Path <path>

This cmdlet adds a new event source. The Type is a string (for example, Survey), and the Source must be valid JSON. Otherwise, an error is thrown.

Alternatively, you can use a -Path parameter that specifies a file path from which the source JSON is to be read.

Update-1EEventSource -Id <id> -Type <type> -Source <source> | -Path <path>

This cmdlet updates an event source.

If the associated event and event subscription(s) have been deployed, you will receive an error message if you attempt to update the event source. To update an event source for an event that has been deployed, you must delete and recreate the event, its subscriptions, and the event source itself, then redeploy.

For example, the following code finds an existing event subscription whose topic is "Device.PerformanceAnomaly" and then removes the subscription (which automatically deletes any event subscription assignments and event sources). It then reads a JSON file containing a new value for the event source, and then adds the event subscription back along with the assignment. Finally it redeploys the active policies.

Note that this code is simplified. Normally, you would capture the properties of the existing event subscription and assignment before deleting them, then put them back as found, rather than putting back hard-coded values as here.

Copy

$e= get-1eeventsubscription | where-object {$_.Topic -eq "Device.PerformanceAnomaLy"}
$s= get-1eeventsource | where-object {$_.Id -eq $e.SourceId}
remove-1eeventsubscription -id $e.Id
$c = get-content currentconfig1.json | convertfrom-json
$src = add-1eeventsource -Type Configuration -Source ($c | convertto-json)
$newsub = add-1eeventsubscription -Topic Device.PerformanceAnomaly -Url https://Foo -Consumer Explorer -SourceId $src.Id
add-1eeventsubscriptionassignment -SubscriptionId $newsub.Id -ManagementGroupId 1
send-1epolicy

Remove-1EEventSource -Id <id> [ -Force ]

This cmdlet removes the specified event source. If -Force is not specified and there are event subscriptions associated with the event source, an error is thrown. If -Force is specified, the event source is deleted and any event subscriptions that reference it have their EventSource property set to null.

Get-1EEventSubscription [-Id <id>]

This cmdlet retrieves the event subscriptions that 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 1E Platform 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 platform database.

If the optional Id parameter is specified, only the event subscription corresponding to that Id is returned.

Add-1EEventSubscription -ConsumerName <consumerName> -Topic <topic> -Url <url> [ -SourceId <sourceid> ]

This cmdlet adds a new event subscription and returns the Id and associated information in the same format as Get-1EEventSubscription -Id.

It is possible to add multiple event subscriptions for the same topic and URL. Event subscriptions are not unique by topic and URL.

Update-1EEventSubscription -Id <id> [ -ConsumerName <consumerName ] [ -Topic <topic> ] [ -Url <url> ] [[ -SourceId <sourceid> ]

This cmdlet updates one or more properties of an existing event subscription.

Remove-1EEventSubscription -Id <id>

This cmdlet removes the event subscription whose Id is defined by the -Id parameter.

Some event subscriptions are used internally by platform subsystems, such as Experience Analytics. 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 platform 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.

If you remove an event subscription, and there were event subscription assignments associated with it, this change is not propagated to endpoints until you redeploy active Endpoint Automation policies, as the Endpoint Automation policy deployment mechanism is also used for events. To ensure that changes you make to event subscriptions and assignments are propagated to endpoints, use the send-1EPolicy cmdlet to redeploy active Endpoint Automation policies (if any).

Alternatively, use the optional -Deploy argument when adding or removing event subscription assignments to force the policy to be redeployed.

Get-1EEventSubscriptionAssignment [-Topic <topic>]

This cmdlet 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-1EEventSubscriptionAssignment -SubscriptionId <subscriptionId> -ManagementGroupId <groupId> [-Deploy ]

This cmdlet 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.

If the optional Deploy parameter is specified, all active Guaranteed State policies (if any) are redeployed. It is necessary to perform a Guaranteed State policy redeploy to cause event subscriptions to be updated on devices, as the policy transfer mechanism is also used for event subscriptions. Also refer to Send-1EPolicy.

Remove-1EEventSubscriptionAssignment -Id <id> [-Deploy ]

This cmdlet 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-1EEventSubscriptionAssignments cmdlet.