Rules

Overview

This section let you configure rules to control your SIM cards, send notifications (email, SMS, push API, etc.) or perform actions (e.g. change rate plan, change SIM Card status), when the rule triggers.

You can configure two types of rules:

Event Rules: handles specific events (e.g. New Device, New Call Detail Record, etc.), that happen during the life cycle of the selected SIM cards.

Usage Rules: handles the usage (e.g. data, SMS, etc.) of the selected SIM Cards, you can customize how the total usage is calculated.

The rules are applicable to all SIM cards, a list of selected SIM Cards or filtered by the selected tags, depending on your choice.

Rules Page

To access the Rules sections, select the options Rules in the sidebar MENU. In the rule section, the main view has three panels, one for each rule type (see picture below), with a table inside that shows the rules created.

rules_main_view4

Example panels with configured rules.

Each row contain the basic information (Label, Type, Date Created) for each rule. In the column Actions you can select if you want to View or Delete the rule.

In the upper right side of each panel there is a ‘+‘ sign, that let you create new Rules for that type.

At the end of this view, there is the History button that redirects you to the rules triggered page.

Create Rules

To create new rules, go to the main Rules page view and click the ‘+‘ sign on each panel to select which type of rule you want to create. You will be redirected to a wizard form that helps you create new rules, divided in five steps:

Label
Rules Triggers
SIM Card(s)
Actions
Notifications

Step 1 - Label

In this step you give a name to the new rule.

rules_create_first_step4

First step in wizard form - Label.

Step 2 - Rules Triggers

In this step, you configure the triggers that rule needs to check to perform the actions or send the notifications. Each rule type has their own configuration, which are described in the next subsections.

Event Rules

First, chose the event you want to configure.

rules_create_event_triggers4

Second step in wizard form - Rules Triggers (Event Rules).

There are currently, six event types to configure:

New Data Session
New Platform Simple Short Message (SMS)
New Device
New Location
New SIM Card State

Each options has their own settings to configure.

New Data Session

When you configure the New Data Session event, you need to chose when you want to receive the notification, at the start of the session or at the end.

rules_create_event_triggers4

Rule triggers when the new data session ends.

New Platform Simple Short Message (SMS)

When you configure the New Platform Simple Short Message (SMS) event, the rule triggers when the selected SIM Cards receives a SMS from the platform or send a SMS to the platform.

note

In the scenario where the SMS was originated from the IoT Portal, the rule is only triggered when the SMS is delivered. Pending and cancelled status do not trigger these type of rules

event_rule_new_sms4

Rule triggers when there are new short message.

New Device

When you configure the New Device event, the rule triggers when the selected SIM Cards have a new IMEI attached. Depending on the rule configuration you can lock SIM Cards to a specific IMEI, or create an IMEI range preventing the SIM Cards to attache to other devices. See below examples for possible configurations:

note

The IMEI prefix must have at least have 8 digits.

event_rule_device_no_to_imei_without_prefix4

Rule triggers when the SIM Card doesn’t have a device attached and receives a new device with an IMEI prefix that doesn’t start with ‘12345678’.

note

This example is a good way for you to lock SIM Cards to a specific IMEI range. You can choose to suspend the SIM Card, when the rule triggers, preventing from using in other devices.

event_rule_device_any_to_any4

Rule triggers when the SIM Card changes from any device to another.

note

This example is a good way for you to lock SIM Cards to any IMEI already attach. You can choose to suspend the SIM Card, when the rule triggers, preventing from using in other devices.

New Location

When you configure the New Location event, the rule triggers when the selected SIM Cards enter a new country or network, depending on your choice.

event_rule_location4

Rule triggers when the SIM Card enters a new country.

note

These type of rules should not be used to influence the network steering of a SIM profile. For example, if there's a rule to suspend the SIM when it attaches to a given network, the SIM will still try to connect to that network, depending on network conditions and SIM profile preferences.

New SIM Card State

When you configure the New SIM Card State event, the rule triggers when the selected SIM Cards changes from one state to another, depending on your choice. See below examples for possible configurations:

event_rule_state_provisioned_active4

Rule triggers when the SIM Card changes from provisioned state to active.

note

This example is a good way to send email, SMS or webhook notifications when a SIM Card is Activated.

event_rule_state_provisioned_active4 Rule triggers when the SIM Card changes from any device to another.

Usage Rules

First, chose the usage you want the rule to control. From the five possible options:

Inbound Call(s)
Outbound Call(s)
Outbound SMS
Data Usage
Number of Data Connection

usage_rule_when

Usage type select list.

The second option let you choose how the rule counts the usage. There are two option:

“Each SIM Card” - the rule tracks the usage for each SIM Card.
“All selected SIM Card(s)” - the rule tracks the usage sum of all SIM Card(s).

usage_rule_sum4

Usage sum type select box.

The third option let you type the usage amount cap, in order to trigger the rule.

usage_rule_usage_cap4

Usage amount box.

The units and the total amount change depending on usage type. See the table below for more information:

Units	Usage Type	Max value
KB	Data Usage	4294967295
MB	Data Usage	4194303
SMS(s)	SMS Usage	4294967295
Seconds	Voice Usage	4294967295
Minutes	Voice Usage	71582788
Hours	Voice Usage	1193046

The fourth option let you choose the period in which the rule gatherers information to calculate to total usage.

usage_rule_period4

Rule period select box.

Period	Comment
Calendar Month	Uses the data of the current month
Billing Cycle	Uses the data of the current billing cycle of the triggered SIM Card
Calendar Week	Uses the data of the current week
Calendar Day	Uses the data of the current day
Past 24 Hours	Uses the data from the last 24 hours
Past 7 Days	Uses the data from the last 7 days
Past 14 Days	Uses the data from the last 14 days
Past 30 Days	Uses the data from the last 30 days
Custom Period	Uses the data from the custom select period, counted in minutes or hours
Last Session	Uses the data from the last session

note

If you select Custom Period it will show the following box:

> Custom Period field in usage rules.

Step 3 - SIM Card(s)

In this step, you select the SIM Card(s) for the rule. There are three possible choices:

SIM Card(s)
Tags
All SIM Cards

SIM Card(s)

Manually select the list of SIM Card(s) from your inventory. Use Ctrl key (or Cmd key in Mac) to select the SIM Card(s) you want to use or not.

rules_sim_cards4

SIM Card list selection box.

note

If your inventory has more than 1000 SIM Card(s), this feature is disable. Apply tags to your SIM Card() and create rules with them (see below).

Tags

If you use the Tags option, the rule will use the SIM Card(s) that have all of the Tags selected. You can create more tags using the Tags section.

rules_sim_tags4

Tags options selection view.

All SIM Card(s)

If you use this option, the rules uses all SIM Cards in your account.

Step 4 - Actions

After selecting the SIM Cards, choose which actions you want the rule to perform in the SIM card(s) if it triggers. You can leave the options blank and the rule will jump this step.

For all rule types you can choose to change the SIM Card status. For examples, if one SIM Card triggers a specific Rule triggers it will suspend the SIM Card(s) in question.

event_usage_rules_action4

Actions step for Event and Usage Rules

note

If rules are being created at sub-organization level then the number of available actions will depend on the permissions that are set for the sub-organization. Example: if a sub-organization is not allowed to change data status then this action will not be available.

Step 5 - Notifications

After selecting or not the actions, choose which notifications you want the rule to send when it triggers. You can leave the options blank and the rule will jump this step.

There are currently four types of notification to send:

Email
SMS
Webhook (Push notification)

rules_notifications4

Notifications step for all the Rules

Email

Sends an email with a default message to multiple destination emails.

rules_step5_multiple_emails Support for multiple notification emails in rules

note

Hit "enter" key after typing each email address to add it to the list of notification destinations.

SMS

Sends a message to the selected number.

The selected number can be the Triggered Number or a Custom Number.

note

SMS’s can only be sent to 1GLOBAL numbers.

The message sent can be the default message (select Default Message) or customizable (select Custom Message).

The following figures shows possible configurations:

rules_notifications4

Send SMS with Custom Number and Custom Message.

rules_rule_actions_sms24

Send SMS with Default Number and Default Message.

Webhook (Push notification)

Sends a push notification to the selected server. The notification payload depend on the type of rule. Each HTTP notification also include the following HTTP headers:

connection
content-type
content-length
user-agent
accept
accept-encoding
host

connection: close
content-type: application/x-www-form-urlencoded
content-length: 81
user-agent: python-requests/2.11.1
accept: */*
accept-encoding: gzip, deflate
host: host.com

Sample HTTP headers

The following sections describe webhook examples for each type of rule.

New data session

{
  "ip_address": "10.10.10.10",
  "session_id": "C258F33800FF02CABCDE",
  "event": 2,
  "duration": 0,
  "iccid": "8944479999999999999",
  "type": "New Data Session",
  "start_date": "2021-02-11 16:10:39.090910+00:00"
}

The parameter event = '2' means that it's a start session event

{
  "end_date": "2021-02-11 16:14:21+00:00",
  "ip_address": "10.10.10.10",
  "session_id": "C258F33800FF02CABCDE",
  "event": 1,
  "duration": 35478.0,
  "iccid": "8944479999999999999",
  "type": "New Data Session",
  "start_date": "2021-02-11 16:10:39+00:00"
}

The parameter event = '1' means that it's an end session event

New Platform Simple Short Message (SMS)

{
  "type": "New Short Message",
  "iccid": "8944479999999999999",
  "sms_type": "MT",
  "date": "2021-02-12+15:18:16+00:00",
  "content": "This is the payload"
}

This refers to a SMS MT or SMS received by the SIM from the portal

{
  "type": "New Short Message",
  "iccid": "8944479999999999999",
  "sms_type": "MO",
  "date": "2021-02-12+15:18:16+00:00",
  "content": "This is the payload"
}

This refers to a SMS MO or SMS sent by the SIM to the portal

New Device

{
  "type": "New Device",
  "iccid": "8944479999999999999",
  "new_imei": "490154203237518",
  "last_update": "2021-02-11 16:10:39+00:00",
  "label": "Device X"
}

New Location

{
  "type": "New Location",
  "iccid": "8944479999999999999",
  "new_country": "United Kingdom",
  "mcc": "234",
  "mnc": "25"
}

New SIM Card State

{
  "type": "New SIM State",
  "iccid": "8944479999999999999",
  "old_state": "PRE-ACTIVE",
  "new_state": "ACTIVE"
}

View Rule Details

You can click in the View button to view the details of a specific rule. The new page will show in a single page the triggers, SIM cards, the actions adn the notifications. You can click Edit to start editing the page.

rules_detail_view4

Details of existing rule.

History

You can click in the History button to view all the list of all the triggered rules and the actions.

rules_history4

History of triggered rules.

To export the information you can click “Export” and choose the method to export the information, see Rules History Export for more information.

Overview​

Rules Page​

Create Rules​

Step 1 - Label​

Step 2 - Rules Triggers​

Event Rules​

New Data Session​

New Platform Simple Short Message (SMS)​

New Device​

New Location​

New SIM Card State​

Step 3 - SIM Card(s)​

Step 4 - Actions​

Step 5 - Notifications​

Email​

SMS​

Webhook (Push notification)​

New data session​

New Platform Simple Short Message (SMS)​

New Device​

New Location​

New SIM Card State​

View Rule Details​

History​

Overview

Rules Page

Create Rules

Step 1 - Label

Step 2 - Rules Triggers

Event Rules

New Data Session

New Platform Simple Short Message (SMS)

New Device

New Location

New SIM Card State

Step 3 - SIM Card(s)

Step 4 - Actions

Step 5 - Notifications

Email

SMS

Webhook (Push notification)

New data session

New Platform Simple Short Message (SMS)

New Device

New Location

New SIM Card State

View Rule Details

History