Event Handler

Overview

The Event Handler feature is a service that allows you to build automations based on SIM events, such as sending email notifications, modifying an Air SIM's speed class, calling an AWS Lambda function, and more, based on a SIM's data usage and status. Event handlers can be applied to an individual subscriber, a group of subscribers, subscribers that contain a particular tag, or to all subscribers in your account.

Parameters

Each event handler consists of the following configuration parameters:

Execution Process

The following process describes the execution logic for an event handler configuration:

  1. Find all subscribers that are defined in the target parameter, then...
  2. Check if the rule condition is met based on its event type and parameters. If yes, then...
  3. For each of the actions defined in the configuration, execute the action immediately or schedule an action to be executed later, then...
  4. Set the event handler configuration to be re-evaluated again immediately, or after a specified delay, or disable re-evaluation.

Limitations

Target Limit Event Handler Rule is applied to...
IMSI 10 per subscriber A single subscriber in your account
Group 10 per group Multiple subscribers in your account which belong to a particular group
Operator 10 total All subscribers in your account

If you require higher limits when configuring event handlers, please contact us.


Configuration

Creating an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

    https://console.soracom.io

    Create Event Handler

  2. Click the Create Event button.

  3. Enter the event handler configuration parameters:

    https://console.soracom.io

    Event Handler Configuration

    • Name (required) - A name that uniquely identifies the event handler.

    • Description (optional) - A brief description that describes the behavior of the event handler.

    • Target (required) - The subscribers that the event handler should be applied to. Available options:

      • IMSI - Matches an individual subscriber. The IMSI of the subscriber is required.
      • Group - Matches all subscribers within a specific group. The Group ID is required.
      • Operator - Matches all subscribers in your account.

      To configure a Tag target rule, use the Advanced Configuration instructions below.

    • Rule (required) - The condition that must be met in order for the event handler configuration to execute its actions. Available options:

      • Daily traffic - Executes when a subscriber's daily data usage reaches a specified value.
      • Monthly traffic - Executes when a subscriber's monthly data usage reaches a specified value.
      • Cumulative traffic - Executes when a subscriber's lifetime cumulative data usage reaches a specified value.
      • Daily total traffic - Executes when the total daily data traffic of all subscribers associated with an Operator reaches a specified value.
      • Monthly total traffic - Executes when the total monthly data traffic of all subscribers associated with an Operator reaches a specified value. - Subscriber status attribute - Executes when a subscriber's status changes and (optionally) matches a specified value.
      • Subscriber speed class attribute - Executes when a subscriber's speed class changes and (optionally) matches a specified value.
      • Subscriber expired - Executes when a subscriber expires based on its Expiration settings.
      • Session status - Executes when a subscriber's session status changes and matches a specified value.

      Regardless of rule, you must also specify the Re-evaluate parameter. When the rule condition is met, this parameter defines how long the event handler should wait before it evaluates the rule again. You can configure longer intervals in order to prevent the event handler from perform actions too frequently. Available options:

      • Immediately - Re-evaluate the rule immediately.
      • Beginning of next month - Re-evaluate the rule at the beginning of the next month.
      • Beginning of next day - Re-evaluate the rule at the beginning of the next day.
      • After one day - Re-evaluate the rule one day (24 hours) later.
      • Never - Do not re-evaluate.
    • Action (one or more required) - Oone or more actions to perform when an event handler configuration's rule condition is met. Available options:

      • Change speed class - Change the subscriber's speed class.
      • Send email - Send an email to a specified email address.
      • Send email to Operator - Send an email to the subscriber's Operator email address.
      • Activation - Set the subscriber's status to Active.
      • Deactivation - Set the subscriber's status to Inactive.
      • Execute web request - Execute a specified HTTP request.
      • Invoke AWS Lambda - Invoke a specified AWS Lambda function.

      For each action, you must also specify the Run parameter. When the rule condition is met, this parameter defines how long the event handler should wait before performing the action. You can configure longer intervals in order to add a delay between the rule and action. Available options:

      • Immediately - Execute the action immediately.
      • Beginning of next month - Execute the action at the beginning of the next month.
      • Beginning of next day - Execute the action at the beginning of the next day.
      • After one day - Execute the action one day later.
      • Never - Do not execute.
    • Active - Enables or disables the event handler.
  4. Click the Create button.

Editing an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

  2. From the list of event handlers, click the name of the event handler that you want to edit.

    https://console.soracom.io

    Edit Event Handler

  3. Enter the event handler configuration parameters.

  4. Click the Update button.

Deleting an Event Handler

  1. Login to the User Console. From the Menu, open the Event Handler screen.

  2. From the list of event handlers, click the for the event handler you want to delete, then click the Delete button.

    https://console.soracom.io

    Delete Event Handler

  3. Click the Delete button again to confirm.

    Delete Event Handler


Advanced Configuration

Configuring an event handler can also be done using either the Soracom API or Soracom CLI. Each event handler configuration is defined using a JSON object, which contains Target, Name and Description, Rule, Action, and Status properties.

When using the API, the JSON is passed in as the data --data '{ ... }' of the HTTP request. The same applies to the CLI as the body --body '{ ... }', however we can pass the JSON in as a file using soracom event-handlers create --body /path/to/settings.json.

Regardless of API or CLI usage, the JSON configuration looks like this:

{
  // Name and description of this event handler configuration:
  "name": "User-defined name",
  "description": "User-defined description",

  // One of the following targets:
  "targetImsi": "IMSI",
  "targetGroupId": "Group ID",
  "targetTag": { "User-defined tag name": "User-defined tag value" },
  "targetOperatorId": "Operator ID",

  // Define the rule condition to check and match:
  "ruleConfig": {
    "type": "ruleType",
    "properties": {
      "key": "value",
      // ...additional condition parameters
    }
  },

  // Define actions to perform when the rule is matched:
  "actionConfigList": [
    {
      "type": "actionType",
      "properties": {
        "key": "value",
        // ...additional action parameters
      }
    },
    // ...additional actions
  ],

  // Set this event handler as active or inactive:
  "status": "active"
}

Name and Description

A name (string, required) and description (string, optional) for the event handler configuration.

  "name": "3GB Limit",
  "description": "Change speed class when an Air SIM reaches 3GB data transfer",

Target

One of the following must be specified as the target of the event handler:

Target Type Description Example
targetImsi Matches an individual subscriber "targetImsi": "295000012345678"
targetGroupId Matches all subscribers within a specific group "targetGroupId": "abcdef00-0000-0000-0000-000012345678"
targetTag Matches all subscribers that contain the specified tag "targetTag": {"my-tag": "my-value"}
targetOperatorId Matches all subscribers in your account "targetOperatorId": "OP0012345678"
  "targetImsi": "295000012345678",

If you use multiple event handler configurations and an individual subscriber is matched in more than one of those configurations, the default behavior is to execute all actions for each configuration. You can further customize event handler status by disabling an action for an individual subscriber, a group of subscribers, or for all subscribers in your account.


Rule

The ruleConfig (object, required) property defines the condition that must be met in order for the event handler configuration to execute its actions. ruleConfig consists of two parameters, type and properties, with the following usage:

  "ruleConfig": {
    "type": "ruleType",
    "properties": {
      "key": "value",
      // ...additional condition parameters
    }
  },

Action

The actionConfigList (array, required) property defines one or more actions to perform when an event handler configuration's rule condition is met. actionConfigList is an array of objects, which each consist of two parameters, type and properties, with the following usage:

  "actionConfigList": [
    {
      "type": "actionType",
      "properties": {
        "key": "value",
        // ...additional action parameters
      }
    },
    // ...additional actions
  ],

For each action:


Status

The status (string, required) property defines whether the event handler configuration is enabled or disabled.

  "status": "active"

Possible values:


Available Rules

Data Usage

Execute actions based on a subscriber's data usage:

  "ruleConfig": {
    "type": "DailyTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_DAY",
      "limitTotalTrafficMegaByte": 100
    }
  },

type:

Rule Type Executes when...
DailyTrafficRule a subscriber's daily data usage reaches a specified value
MonthlyTrafficRule a subscriber's monthly data usage reaches a specified value
CumulativeTrafficRule a subscriber's lifetime cumulative data usage reaches a specified value
DailyTotalTrafficRule the total daily data traffic of all subscribers associated with an Operator reaches a specified value
MonthlyTotalTrafficRule the total monthly data traffic of all subscribers associated with an Operator reaches a specified value

properties:


Status Changes

Execute actions based on a subscriber's status (Active, Inactive, etc.):

  "ruleConfig": {
    "type": "SubscriberStatusAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "NEVER",
      "targetStatus": "ready"
    }
  },

type:

Rule Type Executes when...
SubscriberStatusAttributeRule a subscriber's status changes and (optionally) matches a specified value

properties:

When using SubscriberStatusAttributeRule, the last and current subscriber statuses can be passed into the actions as variables using ${oldStatus} and ${newStatus}.


Speed Class Changes

Execute actions based on a subscriber's speed class (s1.minimum, s1.standard, etc.):

  "ruleConfig": {
    "type": "SubscriberSpeedClassAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "targetSpeedClass": null
    }
  },

type:

Rule Type Executes when...
SubscriberSpeedClassAttributeRule a subscriber's speed class changes and (optionally) matches a specified value

properties:

When using SubscriberStatusAttributeRule, the last and current subscriber speed classes can be passed into the actions as variables using ${oldSpeedClass} and ${newSpeedClass}.


Expiration

Execute actions when a subscriber has expired as a result of its Expiration settings:

  "ruleConfig": {
    "type": "SubscriberExpiredRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY"
    }
  },

type:

Rule Type Executes when...
SubscriberExpiredRule a subscriber expires based on its Expiration settings

properties: (none)

When using SubscriberStatusAttributeRule, the last and current SIM statuses can be passed into the actions as variables using ${oldStatus} and ${newStatus}.


Available Actions

Change Speed Class

Change the subscriber's speed class:

  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "speedClass": "s1.minimum"
      }
    }
  ],

type:

Action Type This action will...
ChangeSpeedClassAction change the subscriber's speed class

properties:


Send Email

Send an email:

  "actionConfigList": [
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "to": "sora@soracom.io",
        "title": "Event Handler Called",
        "message": "This email was sent to inform you that your event handler was called."
      }
    }
  ],

type:

Action Type This action will...
SendMailAction send an email to a specified email address
SendMailToOperatorAction send an email to the subscriber's Operator email address

properties:

The following variables are available for use in the email title or message:


Activate or Deactivate Subscriber

Activate or deactivate the subscriber:

  "actionConfigList": [
    {
      "type": "DeactivationAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY"
      }
    }
  ],

type:

Action Type This action will...
ActivationAction set the subscriber's status to Active
DeactivationAction set the subscriber's status to Inactive

properties: (none)


Run Webhook

Execute an HTTP request (webhook):

  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "url": "https://www.example.com/my/api",
        "httpMethod": "POST",
        "contentType": "application/json",
        "body": "{ \"text\": \"The event handler was called\" }"
      }
    }
  ],

type:

Action Type This action will...
ExecuteWebRequestAction execute a specified HTTP request

properties:

The following variables are available for use in the url, headers, or body parameters:


Invoke AWS Lambda Function

Invoke an AWS Lambda function:

  "actionConfigList": [
    {
      "type": "InvokeAWSLambdaAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "endpoint": "https://lambda.us-east-2.amazonaws.com",
        "functionName": "my-lambda-function",
        "accessKey": "ABC123XXXXXXXXXX",
        "secretAccessKey": "ABC123XXXXXXXXXX",
        "parameter1": "my value",
      }
    }
  ],

type:

Action Type This action will...
InvokeAWSLambdaAction invoke a specified AWS Lambda function

properties:

Each of the parameter parameters can accept any variables passed from the rule, such as ${oldStatus} and ${newStatus} from SubscriberStatusAttributeRule, or ${oldSpeedClass} and ${newSpeedClass} from SubscriberSpeedClassAttributeRule. Note that there is a 100-character limit for each parameter value.

When the InvokeAWSLambdaAction action is executed, the following JSON is passed:

{
  "imsi": "295000012345678",
  "parameter1": "my parameter 1",
  "parameter2": "my parameter 2",
  "parameter3": "my parameter 3",
  "parameter4": "my parameter 4",
  "parameter5": "my parameter 5"
}

The values can be accessed in the Lambda function as properties of the event parameter:

exports.handler = function(event, context) {
  console.log('Function called from IMSI ', event.imsi);
  console.log('The value of parameter1 is ', event.parameter1);
  context.succeed(event.imsi);
};

Examples

Slack Notification

This Event Hander configuration will send a message to a Slack channel using Slack's incoming webhooks API when a subscriber's Speed Class is changed.

{
  "targetOperatorId": "OP0012345678",
  "name": "SpeedClass-Slack",
  "description": "Send a notification to Slack when a Speed Class changes",
  "ruleConfig": {
    "type": "SubscriberSpeedClassAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY"
    }
  },
  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
        "httpMethod": "POST",
        "contentType": "application/json",
        "body": "{\"text\":\"${imsi} speed class changed from ${oldSpeedClass} to ${newSpeedClass}!\"}"
      }
    }
  ],
  "status": "active"
}

Explanation:


Downgrade Speed for One Day

This event handler configuration will execute a series of actions when a specific subscriber reaches 100MB of data usage.

{
  "targetImsi": "295000012345678",
  "name": "100MB-Limit",
  "description": "Slow down for 1 day and notify when 100MB is used",
  "ruleConfig": {
    "type": "DailyTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "AFTER_ONE_DAY",
      "limitTotalTrafficMegaByte": 100
    }
  },
  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "speedClass": "s1.slow"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "to": "sora@soracom.io",
        "title": "High Data Usage",
        "message": "This device has reached 100MB in daily data usage, so its speed will be limited for one day.",
      }
    },
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "speedClass": "s1.fast"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "to": "sora@soracom.io",
        "title": "Device speed limit removed",
        "message": "This device's speed limit has been removed.",
      }
    }
  ],
  "status": "active"
}

Explanation:


Invoke Lambda on Active Status

This event handler configuration will invoke an AWS Lambda function whenever a subscriber's status changes.

{
  "targetOperatorId": "OP0012345678",
  "name": "Status-Lambda",
  "description": "Invoke Lambda function when a SIM is activated",
  "ruleConfig": {
    "type": "SubscriberStatusAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "targetStatus": "active"
    }
  },
  "actionConfigList": [
    {
      "type": "InvokeAWSLambdaAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "endpoint": "https://lambda.us-east-2.amazonaws.com",
        "functionName": "my-lambda-function",
        "accessKey": "ABC123XXXXXXXXXX",
        "secretAccessKey": "ABC123XXXXXXXXXX",
        "parameter1": "${oldStatus}",
        "parameter2": "${newStatus}"
      },
    }
  ],
  "status": "active"
}

Explanation: