Skip to main content

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 three 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:

  1. Label
  2. Rules Triggers
  3. SIM Card(s)
  4. Actions
  5. 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:

  1. New Data Session
  2. New Platform Simple Short Message (SMS)
  3. New Device
  4. New Location
  5. 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:

event_rule_new_sms4

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

note

The IMEI prefix must 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:

  1. Inbound Call(s)
  2. Outbound Call(s)
  3. Outbound SMS
  4. Data Usage
  5. 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:

  1. “Each SIM Card” - the rule tracks the usage for each SIM Card.
  2. “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:

UnitsUsage TypeMax value
KBData Usage4294967295
MBData Usage4194303
SMS(s)SMS Usage4294967295
SecondsVoice Usage4294967295
MinutesVoice Usage71582788
HoursVoice Usage1193046

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.

PeriodComment
Calendar MonthUses the data of the current month
Billing CycleUses the data of the current billing cycle of the triggered SIM Card
Calendar WeekUses the data of the current week
Calendar DayUses the data of the current day
Past 24 HoursUses the data from the last 24 hours
Past 7 DaysUses the data from the last 7 days
Past 14 DaysUses the data from the last 14 days
Past 30 DaysUses the data from the last 30 days
Custom PeriodUses the data from the custom select period, counted in minutes or hours
Last SessionUses the data from the last session
note

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

usage_rule_custom_period4 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:

  1. SIM Card(s)
  2. Tags
  3. 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

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:

  1. Email
  2. SMS
  3. Webhook (Push notification)

rules_notifications4

Notifications step for all the Rules

Email#

Sends an email with a default message to the selected email.

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 Truphone 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.