# Example Configurations

Examples for common SIM automation requirements.

## Disable SIMs That Use More Than 25MB in a Month

This Event Handler configuration will set any SIM in your account that exceeds 25MB of data in a month to Inactive status, send an email to the specified address identifying the SIM that has exceeded the limit, and reactivate any SIM cards deactivated this way at the start of the next month.

```json
{
  "targetOperatorId": "OP0012345678",
  "name": "25MB-Cap",
  "description": "Deactivate until next month when 25MB is used",
  "ruleConfig": {
    "type": "SimMonthlyTotalTrafficRule",
    "properties": {
        "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH",
        "limitTotalTrafficMegaByte": 25
    }
  },
  "actionConfigList": [
    {
      "type": "DeactivationAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
          "executionDateTimeConst": "IMMEDIATELY",
          "to": "sora@soracom.io",
          "title": "${simId} Has Exceeded the Data Usage Threshold",
          "message": "${simId} has exceeded the 25 MB monthly data usage threshold configured in your account. It has been deactivated and will be automatically reactivated at the start of next month."
      }
    },
    {
      "type": "ActivationAction",
      "properties": {
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH"
      }
    }
  ],
  "status": "active"
}
```

Explanation:

- This event handler will apply to all SIMs that belong to **targetOperatorId** `OP0012345678`.

- It uses the **SimMonthlyTotalTrafficRule** rule, with the **limitTotalTrafficMegaByte** parameter set to `25`, which will cause the rule to execute when the SIM exceeds 25MB of data usage in a month.

- The rule interval **inactiveTimeoutDateConst** is set to `BEGINNING_OF_NEXT_MONTH`, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait until the start of the next month before checking the SIM that triggered it again.

- The event handler contains three actions:

  1. **DeactivationAction** which will `IMMEDIATELY` change the SIM status to `Inactive`.
  2. **SendMailAction** which will `IMMEDIATELY` send an email notification informing a user of the deactivation.
  3. **ActivationAction** which will set the SIM status to `Active` at the `BEGINNING_OF_NEXT_MONTH`.

## Send Slack Notifications on Speed Class Change

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

```json
{
  "targetOperatorId": "OP0012345678",
  "name": "SpeedClass-Slack",
  "description": "Send a notification to Slack when a Speed Class changes",
  "ruleConfig": {
    "type": "SimSpeedClassAttributeRule",
    "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:

- This event handler will apply to all subscribers that belong to **targetOperatorId** `OP0012345678`.
- It uses the **SimSpeedClassAttributeRule** rule, and _omits_ the **targetSpeedClass** parameter, which means the rule will match all speed class changes.
- The rule interval **inactiveTimeoutDateConst** is set to `IMMEDIATELY`, meaning that once the rule conditions are met, the rule will be effective again with no delay.
- The event handler contains one action:
  1. **ExecuteWebRequestAction**, which is configured to `IMMEDIATELY` send a `POST` request to `https://hooks.slack.com/services/...`, with content type `application/json`, and custom body content which includes variables `${imsi}`, `${oldSpeedClass}`, and `${newSpeedClass}`.

## Downgrade Speed for One Day When 100MB Is Consumed

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

```json
{
  "targetImsi": "295050012345678",
  "name": "100MB-Limit",
  "description": "Slow down for 1 day and notify when 100MB is used",
  "ruleConfig": {
    "type": "SubscriberDailyTrafficRule",
    "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:

- This event handler applies to an individual subscriber with **targetImsi** `295050012345678`.

- It uses the **SubscriberDailyTrafficRule** rule, with the **limitTotalTrafficMegaByte** parameter set to `100`, which will cause the rule to execute when the subscriber exceeds 100MB of data usage.

- The rule interval **inactiveTimeoutDateConst** is set to `AFTER_ONE_DAY`, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait one day before checking again.

- The event handler contains four actions:

  1. **ChangeSpeedClassAction**, which will `IMMEDIATELY` change the speed class to `s1.slow`.
  2. **SendMailAction**, which will `IMMEDIATELY` send an email notification informing a user of the speed change.
  3. **ChangeSpeedClassAction**, which will reset the speed class to `s1.fast` `AFTER_ONE_DAY` passes.
  4. **SendMailAction**, which will send another email notification `AFTER_ONE_DAY` informing the user that the speed limit has been removed.

## Invoke Lambda on Change to Active Status

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

```json
{
  "targetOperatorId": "OP0012345678",
  "name": "Status-Lambda",
  "description": "Invoke Lambda function when a SIM is activated",
  "ruleConfig": {
    "type": "SimStatusAttributeRule",
    "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:

- This event handler will apply to all subscribers that belong to **targetOperatorId** `OP0012345678`.
- It uses the **SimStatusAttributeRule** rule, with the **targetStatus** parameter set to `"active"`, which will cause the rule to execute when any SIM is activated (status is changed to **Active**).
- The rule interval **inactiveTimeoutDateConst** is set to `IMMEDIATELY`, meaning that once the rule conditions are met, the rule will be effective again with no delay.
- The event handler contains one action:
  1. **InvokeAWSLambdaAction**, which is configured to `IMMEDIATELY` invoke the `my-lambda-function` function at `https://lambda.us-east-2.amazonaws.com` using the provided access key, pass the SIM's previous and current statuses to the Lambda function in the properties **parameter1** and **parameter2** respectively.

## Automatically Apply IMEI Lock When a SIM Comes Online

This event handler configuration automatically applies IMEI Lock to an IoT SIM the first time it connects with a device. This is useful for fleet onboarding scenarios where you want each SIM to become associated with the first device that uses it and prevent unauthorized SIM swapping.

Before using this configuration:

- Session events must be enabled for the target group. See [Enabling Session Events for a Group](https://docs.soracom.io/en/services/event-handler/configuration#enabling-session-events-for-a-group).
- [contact Soracom Support](https://docs.soracom.io/en/services/account/support#creating-a-support-request) to enable the **Sim session status changed** rule for your account.

```json
{
  "targetGroupId": "<GROUP-ID>",
  "name": "IMEI-Lock-On-First-Connect",
  "description": "Automatically apply IMEI Lock when SIM first comes online",
  "ruleConfig": {
    "type": "SimSessionStatusRule",
    "properties": {
      "targetSessionStatus": "Created",
      "hasImei": true,
      "inactiveTimeoutDateConst": "NEVER"
    }
  },
  "actionConfigList": [
    {
      "type": "ImeiLockAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "to": "<EMAIL>",
        "title": "IMEI Lock applied to ${simId}",
        "message": "SIM ${simId} has been locked to the reported IMEI."
      }
    }
  ],
  "status": "active"
}
```

Explanation:

- This event handler applies to all SIMs in the group specified by **targetGroupId**.

- It uses the **SimSessionStatusRule** rule with **targetSessionStatus** set to `"Created"`, which triggers when a SIM session is created (the SIM comes online).

- The **hasImei** property is set to `true`, ensuring the rule only triggers for session events that include an IMEI. This is required because IMEI Lock cannot be applied without knowing the device's IMEI.

- The rule interval **inactiveTimeoutDateConst** is set to `NEVER`, which prevents the rule from being re-evaluated after it is triggered. This is appropriate when IMEI Lock should only be applied once during initial onboarding.

- The event handler contains two actions:

  1. **ImeiLockAction**, which `IMMEDIATELY` locks the SIM to the IMEI reported by the device.
  2. **SendMailAction**, which `IMMEDIATELY` sends an email notification for audit or operational visibility.

Once IMEI Lock is applied, subsequent connections from a different IMEI will be rejected according to IMEI Lock behavior. For more information, see [IMEI Lock](https://docs.soracom.io/en/services/air/imei-lock).