SORACOM Developers

Documents

Details on event handler function

Introduction

SORACOM Air’s “supervision” function is carried out internally using an event handler function. With the event handler function it is possible to carry out e-mail notifications, speed-class modifications, and AWS Lambda functions based on thresholds for data transfer capacity to a specific SIM, a specific group, a specific tag, or all SIMs. If more complex processing is desired than what is found in the User Console’s “supervision” settings, configuration must be carried out using the API of the event handler.


Configuration method

Configuration is carried out by a POST (Create Event Handler) to /event_handlers. If this is created using soracom-cli, then it is soracom event-handlers create --body @{path to JSON file} JSON will have a structure like the following:

{
  "handlerId": "Used when updating the ID of the handler",

  //Set targetImsi,targetOperatorId,targetTag,targetGroup
  "targetImsi": "IMSI number",
  "targetOperatorId": "OperatorId",
  "targetTag": { "Tag name":"Value" },
  "targetGroupId": "Group ID",

  "name": "Display name",
  "description": "Handler details",
  "ruleConfig": {
    "type": "Rule type",
    "properties": { "key": "value" }
  },
  "actionConfigList": [
    {
      "type": "Action type",
      "properties": { "key": "value" }
    }
  ]
}

To give a specific example, if a setting (a limit of 1GB per month) is input from the User Console, then verification by means of the soracom-cli command soracom event-handlers list will reveal a configuration such as the following:

{
  "handlerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "targetImsi": null,
  "targetOperatorId": "OP0000000000",
  "targetTag": null,
  "targetGroupId": null,
  "name": "Prefixed event handler",
  "description": null,
  "ruleConfig": {
    "type": "MonthlyTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH",
      "limitTotalTrafficMegaByte": "1000"
    }
  },
  "status": "active",
  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "speedClass": "s1.minimum",
        "executionDateTimeConst": "IMMEDIATELY"
      }
    },
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "speedClass": "s1.standard",
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH"
      }
    },
    {
      "type": "SendMailToOperatorAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "message": "The monthly traffic of SIM ${imsi} \n\nSIM has reached 1,000MiB, so its communication speed has been limited",
        "title": "Notification of speed limitation"
      }
    },
    {
      "type": "SendMailToOperatorAction",
      "properties": {
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH",
        "message": "The speed limitation period of SIM ${imsi} \n\n has concluded, so the speed has returned to its original value",
        "title": "Notification of removal of speed limitation"
      }
    }
  ]
}

The individual parameters will be discussed in detail in the next section.


target

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

If the criteria of multiple rules (e.g., IMSI unit and total OperatorId) are satisfied at the same time, the default is that both actions are executed. However, it is also possible to disable the action for a group, all SIMs, etc., from the Supervision tab of SIM Details.

SIM Details — Supervision settings


ruleConfig

These are rules that determine whether or not an action will be performed. For instance, by setting a rule such as “Perform action if monthly traffic exceeds __ MiB” it is possible to perform the action specified.

{
  "ruleConfig": {
    "type": "Rule type",
    "properties": { "key": "value" }
  }
}

The rule to be used is specified by means of the “type” attribute. In addition, for each rule it is possible to set “inactiveTimeoutDateConst” as a common parameter. After a rule has been applied, this specifies a period of time during which the rule will not be reevaluated. For example, if an action is to be performed after a certain number of MiB have been used in a given month, then once the rule has matched it is possible to exclude the rule from evaluation until the next month by specifying BEGINNINGOFNEXT_MONTH.

type
DailyTrafficRule
A rule that performs an action if a SIM’s daily data traffic exceeds a certain value
MonthlyTrafficRule
A rule that performs an action if a SIM’s monthly data traffic exceeds a certain value
CumulativeTrafficRule
A rule that performs an action if a SIM’s cumulative data traffic since its first use exceeds a certain value
DailyTotalTrafficRule
A rule that performs an action if the total daily data traffic of all SIMs associated with an Operator exceeds a certain value
MonthlyTotalTrafficRule
A rule that performs an action if the total monthly data traffic of all SIMs associated with an Operator exceeds a certain value
SubscriberStatusAttributeRule
A rule that performs an action if a SIM’s status is modified
SubscriberSpeedClassAttributeRule
A rule that performs an action if a SIM’s speed class is modified
SubscriberExpiredRule
A rule that performs an action if a SIM expires
properties
inactiveTimeoutDateConst
A required property that is set for each rule. After a rule has been performed, it specifies the timing for reevaluation of the rule.
The values that “inactiveTimeoutDateConst” can have are as follows:
IMMEDIATELY
Perform again right away
BEGINNING_OF_NEXT_MONTH
Perform at the beginning of the next month
BEGINNING_OF_NEXT_DAY
Perform at the start of the next day
AFTER_ONE_DAY
Perform one day later
NEVER
Do not perform or reevaluate

Rule list

A rule that performs an action if a SIM’s daily data traffic exceeds a certain value
type
“DailyTrafficRule”
limitTotalTrafficMegaByte
Performs the action if this data quantity (in MiB) is exceeded
A rule that performs an action if a SIM’s monthly data traffic exceeds a certain value
type
“MonthlyTrafficRule”
limitTotalTrafficMegaByte
Performs the action if the data quantity (in MiB) exceeds this quantity
A rule that performs an action if a SIM’s cumulative data traffic since its first use exceeds a certain value
type
“CumulativeTrafficRule”
limitTotalTrafficMegaByte
Performs the action if the cumulative data quantity (in MiB) exceeds this value
A rule that performs an action if the total daily data traffic of all SIMs associated with an Operator exceeds a certain value
type
“DailyTotalTrafficRule”
limitTotalTrafficMegaByte
Performs the action if the data quantity (in MiB) exceeds this quantity
This rule is valid only if the target is “targetOperatorId” or “targetTag.”
A rule that performs an action if the total monthly data traffic of all SIMs associated with an Operator exceeds a certain value
type
“MonthlyTotalTrafficRule”
limitTotalTrafficMegaByte
Performs the action if the data quantity (in MiB) exceeds this quantity
This rule is valid only if the target is “targetOperatorId” or “targetTag.”
A rule that performs an action if a SIM’s status is modified
type
“SubscriberStatusAttributeRule”
targetStatus
Performs the action if the Subscriber acquires this status. For example, if “targetStatus” is set to “inactive,” then if the SIM becomes inactive the specified action can be performed.
The values that “targetStatus” can have are as follows:
null
All status
ready
ready status
active
active status
inactive
inactive status
suspended
suspended status
terminated
terminated status
Supported variables (If configured in the action, these variables can acquire their value when the action is performed.)
${newStatus}
The status after the modification
${oldStatus}
The status before the modification
A rule that performs an action if a SIM’s speed class is modified type
type
“SubscriberSpeedClassAttributeRule”
targetSpeedClass
The action is performed if the Subscriber acquires this speed class. For example, if “targetSpeedClass” is set to “s1.minimum,” then if the SIM acquires the s1.minimum speed class the action can be performed.
The values that “targetSpeedClass” can have are as follows:
null(Not set
All speed classes
s1.minimum
s1.slow
s1.standard
s1.fast
A rule that performs an action if a SIM expires
type
“SubscriberExpiredRule”
 Supported variables (If configured in the action, these variables can acquire their value when the action is performed.)
${newStatus}
The status after expiration
${oldStatus}
The status before expiration

actionConfigList[]

Actions that are performed when a rule is applied. For instance, actions such as sending an e-mail to a specified address or changing a SIM’s type are possible.

{
  "actionConfigList": [
    {
      "type": "Action Type",
      "properties": { "key": "value" }
    }
  ]
}

Just as in the case of rules, the action to be used can be specified by means of the “type” attribute. In addition, “executionDateTimeConst” can be set as a common parameter. “executionDateTimeConst” is a parameter that regards when the action should be performed.

type
ChangeSpeedClassAction
Action that changes a SIM’s speed class
SendMailAction
Action that sends e-mail
SendMailToOperatorAction
Action that sends e-mail to the Operator’s registered e-mail address
ActivationAction
Action that changes a SIM’s status to Active
DeactivationAction
Action that changes a SIM’s status to Inactive
ExecuteWebRequestAction
Action that makes requests to specified URLs
InvokeAWSLambdaAction
Action that invokes AWS Lambda
properties
executionDateTimeConst
A required parameter that is common to all actions. When a rule is determined to be valid, this parameter specifies with what timing the action should be performed.
The values that “executionDateTimeConst” can have are as follows:
IMMEDIATELY
Perform again right away
BEGINNING_OF_NEXT_MONTH
Perform at the beginning of the next month
BEGINNING_OF_NEXT_DAY
Perform at the start of the next day
AFTER_ONE_DAY
Perform one day later
NEVER
Do not perform or reevaluate

The parameters that are specific to the individual actions are explained below.

Actions

At present the following actions have been implemented:

Actions to modify a SIM’s speed class
type
“ChangeSpeedClassAction”
speedClass
Sets the SpeedClass, e.g., “s1.standard”
Action that sends e-mail
type
“SendMailAction”
to
E-mail address of destination
title
Title of e-mail
message
Body of e-mail
The following variables can be used in the title and body of e-mails:
${imsi}
The IMSI of the SIM
${operatorId}
The ID of the Operator who possesses the SIM
${date}
Date of sending (yyyy/m/d)
${year}
Year of sending (yyyy)
${month}
Month of sending (m)
${date}
Day of sending (d)
Other variables that are supported by rules can also be used.
Action that sends e-mail to the Operator
type
“SendMailToOperatorAction”
title
title
message
Body of e-mail
In the title and body of e-mails, the same variables can be used as in “Action that sends e-mail.”
Action that changes a SIM’s status to Active
type
“ActivationAction”
Action that changes a SIM’s status to Inactive
type
“DeactivationAction”
Action that makes requests to specified URLs
type
“ExecuteWebRequestAction”
url
URL link and parameters
httpMethod
Either GET, POST, PUT, or DELETE
contentType
ContentType such as application/json
headers
Value to be set in header (hash) (optional)
body
Character string to be set in body of request (optional). Cannot be set in the case of GET or DELETE.
In the title and body of e-mails, the same variables can be used as in “Action that sends e-mail.”
The following variables can be set in the URL, headers, and body:
${imsi}
The IMSI of the SIM
${operatorId}
The ID of the Operator who possesses the SIM
${date}
Date of sending(yyyy/m/d)
${year}
Year of sending (yyyy)
${month}
Month of sending (m)
${date}
Day of sending (d)
Other variables that are supported by rules can also be used.

Example of settings for ExecuteWebRequestAction for a sample

A sample that is communicated to Slack when the speed of a Subscriber is modified


{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "SpeedClass",
  "description": null,
  "ruleConfig": {
    "type": "SubscriberSpeedClassAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY"
    }
  },
  "status": "active",
  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "url": "https://hooks.slack.com/products/XXXX(SlackのWebHook URL)",
        "httpMethod": "POST",
        "contentType":"application/json; charset=utf-8",
        "body":"{\"text\":\"${imsi} speed class changed. from ${oldSpeedClass} to ${newSpeedClass}\"}"
      }
    }
  ]
}

Action that invokes AWS Lambda
type
“InvokeAWSLambdaAction”
endpoint
Endpoint URL of Lambda
functionName
Lambda function name
accessKey
Access key
secretAccessKey
Secret access key
parameter1
parameter1(optional)
parameter2
parameter2(optional)
parameter3
parameter3(optional)
parameter4
parameter4(optional)
parameter5
parameter5(optional)
In the parameter, optional character strings (max. 100 characters) and rule-supported variables (e.g., ${newSpeedClass}) can be configured
In the invoked Lambda function, the following JSON is provided:
{
  "imsi":"The IMSI",
  "parameter1":"Parameter1 above",
  "parameter2":"Parameter2 above",
  "parameter3":"Parameter3 above",
  "parameter4":"Parameter4 above",
  "parameter5":"Parameter5 above"
}
Example of Lambda function implementation
exports.handler = function(event, context) {
    console.log('imsi =', event.imsi);
    console.log('value1 =', event.parameter1);
    context.succeed(event.imsi);
};

Example of sample settings for InvokeAWSLambdaAction

Due to daily usage of 100M, speed limitation until one day later

{
  "targetImsi": "111333444555566",
  "name": "100MiB Limit",
  "description": "Due to daily usage of 100M, speed limitation until one day later",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "AFTER_ONE_DAY",
      "limitTotalTrafficMegaByte": 100
    },
    "type": "DailyTrafficRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "speedClass": "s1.slow"
      },
      "type": "ChangeSpeedClassAction"
    },
    {
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "speedClass": "s1.fast"
      },
      "type": "ChangeSpeedClassAction"
    },
    {
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "message": "The data traffic for the day has reached 100MiB, so the speed has been limited",
        "title": "A notification from SORACOM",
        "to": "notify@exmaple.com"
      },
      "type": "SendMailAction"
    } ,
    {
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "message": "The speed limitation has been removed",
        "title": "A notification from SORACOM",
        "to": "notify@exmaple.com"
      },
      "type": "SendMailAction"
    }
  ]
}

Invoking AWS Lambda when cumulative usage reaches 3GB

Because this is a cumulative event, the inactiveTimeoutDateConst is set to “NEVER”, which carries out evaluation only once.

{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "3GB Limit",
  "description": "When cumulative usage reaches 3GB",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "NEVER",
      "limitTotalTrafficMegaByte": 3000
    },
    "type": "CumulativeTrafficRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "secretAccessKey": "XXXXXXXXXXXXXX",
        "endpoint": "https://lambda.ap-northeast-1.amazonaws.com",
        "accessKey": "XXXXXXXXXXXXXX",
        "functionName": "Lambda function name",
        "executionDateTimeConst": "IMMEDIATELY",
        "parameter3": "param3",
        "parameter2": "param2",
        "parameter1": "param1"
      },
      "type": "InvokeAWSLambdaAction"
    }
  ]
}

Saving history via AWS Lambda when speed class is modified

Uses the variables (${newSpeedClass},${oldSpeedClass}) that can be used in rules for the modification of speed class. Because the speed class before and after modification are provided to the specified AWS Lambda as parameters, they are saved historically via the Lambda program in, e.g., a database.

{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "SpeedClass modified",
  "description": "Performed when speed class is modified",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "targetSpeedClass":null
    },
    "type": "SubscriberSpeedClassAttributeRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "secretAccessKey": "XXXXXXXXXXXXXX",
        "endpoint": "https://lambda.ap-northeast-1.amazonaws.com",
        "accessKey": "XXXXXXXXXXXXXX",
        "functionName": "Lambdaのfunction名",
        "executionDateTimeConst": "IMMEDIATELY",
        "parameter1": "${oldSpeedClass}",
        "parameter2": "${newSpeedClass}"
      },
      "type": "InvokeAWSLambdaAction"
    }
  ]
}

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop