IoT Accelerator Developer Portal
Home Learn Tutorials One-time trigger events management tutorial
In this section

One-time trigger events management tutorial

IoT Accelerator provides the possibility to manage triggers through the service portal and APIs.

A trigger can be defined to automate events (notifications or actions) and can eliminate the need to manually monitor subscriptions. With triggers, the service provider and its enterprise customers can prevent the misuse of its subscriptions or manage their life cycle.

Trigger groups can apply to subscriptions on an enterprise or a subscription package level and include rules that initiate actions if a condition is met. The conditions and the actions are parameters that can be assigned to each individual rule and combined together to be included in a trigger group (the term “group” or “package” is because it is possible to can chain multiple criteria in the same trigger).

Trigger principles

The purpose of setting up a trigger is to be notified or take actions when some configurable and predefined criteria are met: e.g. if given thresholds of data traffic are overcome then either send an email or pause the SIM, or because the device is «silent» for too much time or instead initiated too many data sessions in a given timeframe

Each set of policy rules is named trigger package (since it may contain a mix of criteria) and can be created, updated, canceled.

Trigger definitions and management are organized in 2 different sections:

Trigger Management Legacy: the first set of selectable predefined rules (mainly based on data traffic or mobile activity of the device) to compose the trigger logic.

Trigger Management Non-Legacy: where additional trigger groups can be defined on the base of other criteria (device change, network change, data usage).

If the trigger has already fired for a subscription, it will not fire again. Therefore, if you want to repeat a trigger test for the same subscriptions in the same time period, create a new trigger group or a new rule within your existing trigger group.

Principles for Trigger Management (Legacy)

The following table summarizes the different rules available in Trigger Management Legacy, to be used to set up trigger groups. The application of those rules may be limited or extended to one or more subscription packages of a given enterprise.

Each rule type contains one or more rules to be choosen and applied to match a given criteria, and comes with an example of purpose to better describe its function.

 

Rule Type

Principle

Example of purpose

UsageBased

Device generates too much or too less data/SMS traffic in a timeframe

E.g. Device generating too much or too less traffic compared to the expected amount may be suspect of malfunctioning

Device established too many data session in a timeframe

E.g. Device can be malfunctioning

Device does not talk to the network for too much time

E.g. Device that does not interact with the network for too long time could be powered off

Location based

no LocUpdate

Device does not report its location for too much time, while it is supposed to move on the ground, may be suspect

Roaming not allowed

Device overcome the border of your operator network, like be gone outside your country

Zone Based

Data/SMS traffic generated as roaming in given network group. A Network Group binds networks of several countries.

Device that generates too much or too less data/SMS traffic outside the border of its own home network may lead to unwanted costs

 

 

Tutorial for Trigger Management (Legacy)

Trigger management using service portal GUI

Through the menu operation > automation > trigger management (legacy), trigger packages can be created, vied or modified. Trigger packages include the connection to subscription packages, and the rules that initiate alerts or actions (deactivations) if a subscription reaches the thresholds within a certain period of time (time frame). The threshold and time frame are parameters that can be assigned to each individual rule included in your trigger package.
Also 2 thresholds can be set, for instance the 1st  to get an alarm then the 2nd to pause the SIM.
Click on “create new trigger package” in the next screen.

The “new trigger package” page will let to define details for the  trigger group as well as rules and conditions to trigger a specific alert.

In the “general information” tab it’s possible to specify a name and a description for the trigger group.

The “usage-based rules,” “location-based rules” and “zone traffic rules” are, respectively, tabs including the rules described in the previous chapter.

Rules can be easily managed by:

  • clicking “add new rule” to select the rule to add from the drop-down list
  • clicking the “delete” bin icon to delete a rule from a trigger package
  • using the “+” to add new rules to a group of rules

To limit or extend to one or more subscription packages of a given enterprise, select an enterprise from the organization selector to view its available subscription packages.

To assign a subscription package to a trigger package, tick the box next to the ID of the subscription package.

Define the email addresses to notify in case of alert.
Note that email addresses are defined on enterprise level and all changes will be applied to all triggers belonging to the selected enterprise.

Save the trigger group by clicking on “Save”.

Trigger Management using SOAP APIs

The legacy triggers can be managed also using the service portal APIs. The Developer section of the portal contains a specific API collection which can be found under Testing IoT Accelerator SOAP API in Postman® under Trigger package management heading.

Principles for Trigger Management (Non-Legacy)

Trigger management (Non-legacy) is an extended set of rules and criterias used to create trigger groups.

There are some differences with the legacy version, that can be summarized as follow:

  • the rule can be applied flat to the whole enterprise or may be applied to a given set of subscription packages (and then to all belonging subscriptions that are part of it)
  • the rule can be categorized with a tag that expresses its intention. Useful to filter the rules later on by tag (criterias to design the rule are not constrained by the category; the category is just a label sticked by the user to make it easy searchable)
  • criterias are grouped by 4 classes: Device Change, Network Change, Data Usage and Scheduled Actions.
  • the actions/alerts include also the use of STOMP notification
  • conditions for “Device Change” are extended
  • scheduled actions are added, and they they are triggered at a specific time after the defined time has passed

 

The table below summarizes the rules availabe in the UI. For each rule, a subset of options is described together with the associated actions.

 

Rule Class

Rule options

Rule actions

Device Change: Device change triggers are triggered when the SIM card is removed from the device and inserted into another one.

a) if the new IMEI value detected from the network (the detected IMEI) does not match the previous detected IMEI.
b) if the new detected IMEI value does not match the IMEI of the device assigned by the user (the assigned IMEI).
c) if the beginning of the new detected IMEI does not match  the first part of an IMEI number

–Change subscription package to
–Deactivate subscription
–Pause subscription
–Send notification
–Send STOMP notification
–Terminate subscription

Network change triggers are triggered when the subscription connects to a selected network or leaves a selected network.

a) Network is: if the network changes to one of the selected networks in the list
b) Network is not: if the network is not one of the selected networks in the list

–Change subscription package to
–Deactivate subscription
–Pause subscription
–Localize (swap eUICC profile)
–Send notification
–Send STOMP notification
–Terminate subscription

Data Usage: Data usage triggers are triggered when the subscription has consumed either more or less (depending on the condition set) than the defined amount of data within the defined time frame.

a) Home network or roaming: sets several option on "where" the traffic was generated
b) Data overrun or underrun: sets several options on "how much" data are produced in a time window

For data overrun triggers, the following actions can be selected –Change subscription package to
–Deactivate subscription
–Pause subscription
–Send notification
–Send STOMP notification
–Terminate subscription

For data underrun triggers, the following actions can be selected
–Change subscription package to
–Send notification
–Send STOMP notification

Scheduled Actions: Scheduled actions triggers are triggered when a defined time period has ended.

a) If subscription has been in subscription package for more than
b) If time since last provisioning is more than
c) If date and hour is

The scheduled actions rule contains the following actions:
–Change subscription package to
–Deactivate subscription
–Pause subscription
–Send notification
–Send STOMP notification
–Terminate subscription

 

 

Tutorial for Trigger Management (Non-Legacy)

Through the menu operation > automation > trigger management, trigger groupes can be created, vied or modified.

Click on “create new” in the next screen.

In the “select target” screen, it’s possibile to define whether the new trigger can be defined and applied to the whole enterprise organization or a selection of Subscripion Package.

By clicking the “add filter” button, it’s possible to filter subscription packages by ID, Name or Enterprise.

Select your target and click “next”.

In the “Select rule category" a rule can be applied to build a trigger group.

Rules may belong to various categories reffering to their purpose, as shown in the figure.

The “Input rules details” page will let set the conditions and relative actions for your target group.

Conditions and actions are grouped in headings, and can be summarized as follow:

Device change: a device change event happens when the SIM card is removed from or inserted into a device, and the network detects a new device IMEI value. The new detected IMEI value may also be compared to the user assigned device IMEI or a range of IMEIs to trigger appropriate actions.

Network Change: Network change triggers are triggered when the subscription connects to a selected network, or leaves a selected network. Individual networks, countries/regions (selecting all networks within each country/region) can be selected when defining conditions.

Data usage: Data usage triggers are triggered when the subscription had consumed more than the defined amount of data within the defined time frame.

By clicking on the button close to each group heading its content will expand.

The “IF” statement represents the condition to be used. Select the  condition from the available options in the dropdown menu.

Add more conditions by clicking on the “+IF” button link in the upper right corner of the tab.

The “THEN” statement represent the action to trigger if the above condition is true.

Add more actions by clicking on the “+THEN” button link in the lower part of the tab.

Move to another tab by enabling the correspondent heading.

When done, click on “Next” to move to the next page.

Select the owner of the trigger group you’ve created, and click on “Next”.

The owner and all organizations above it in the hierarchy are able to view and edit the trigger group if they have the corresponding permission.

Note: The organizations available in this view change depending on the enterprises or subscription packages selected in the Target tab.

The next page shos the Summary. Use the Summary tab to overview the settings entered in the previous tabs. From this screen is possible to save the trigger group as a draft, or to save/enable it by clicking on “Complete”.