Automatically Switching SIM Groups Upon Subscription Container OTA Completion

Disclosure based on the operational standards for "Representations which make it difficult for general consumers to distinguish whether they are representations of business operators" (Stealth Marketing regulations): This article was written by an employee belonging to SORACOM INC. as of the date listed. However, it is a personal post and does not represent the official views or statements of SORACOM INC.

Objective

We will move the group that a SIM belongs to at the same time as the plan (subscription) change via OTA (Over The Air) is completed.

While the subscription container OTA is executed after being configured in the User Console, the actual timing for the subscription to switch and the new plan to be applied varies depending on the communication status and the progress of various processes occurring in between.

In this blog, I will introduce a method to change the SIM group simultaneously with the subscription switch, allowing you to update group settings such as SORACOM Beam just-in-time.

Implementation Method

We detect the completion of the subscription container OTA using an Event Handler and execute a SORACOM Flux Webhook at the moment of detection.
Triggered by the SORACOM Flux Webhook, the SORACOM API is executed to change the SIM group.

Prerequisites

• SORACOM Account
• SORACOM IoT SIM
• Destination server for SORACOM Beam, etc. (This part will not be covered in this blog)

Steps

SIM and Group Settings

In this article, we will explain how to move a SIM to a new group triggered by the completion of a subscription container OTA.
Therefore, it is assumed that the target SIM already belongs to a specific group and that the destination group has been created.

0. (Prerequisite) All SIMs before migration are assumed to belong to the same group.
   In this example, we assume all SIMs belong to a group named "group_from" as shown below.
   

1. Create the new destination group.
   Select "SIM Groups" from the hamburger menu,
   
   and click "Add".
   
   In this case, we will create a group named "group_to".
   Make a note of this group's ID (UUID), as it will be used in later steps.
   
   Once created, configure the necessary settings (Beam transfer settings, etc.).

SORACOM Flux Settings

The settings described in this section involve SORACOM Flux, which executes the SORACOM API to change the group after receiving a Webhook notification that the OTA is complete.

Ultimately, you will create a flow like the one shown below. Detailed steps will follow later.

1. Trigger Setting
   Receive a webhook (OTA completion notification) from the Event Handler.
   Event Source: API/Manual execution
   Setting: Incoming webhook
   Output Channel: API Channel
   

2. SORACOM API Action
   Input Channel: API Channel

   API Action Block Settings

   Input payload

   {
       "imsi": "9xxxxxxxxxxxxx",
       "simId": "89423xxxxxxxxxxxx",
       "subscription": "planXX", // New OTA plan name
       "otastatus": "finished" // OTA progress: started, finished, error
   }
   

   Configuration Details

   Category	Item	Value	Remarks
   CONDITION	Execution condition	payload.otastatus == "finished"
   CONFIG	URL	POST /v1/sims/${payload.simId}/set_group	Select setSimGroup and set the {sim_id} placeholder to ${payload.simId}
   CONFIG	HTTP Body	{ "groupId": "{Destination Group UUID}" }
   OUTPUT	Send output to another channel	Disabled

   Setting Screen (Example)
   

3. Notify OTA Progress
   Input Channel: Output Channel

   Slack Notification Action Settings

   Input payload

   {
       "imsi": "9xxxxxxxxxxxxx",
       "simId": "89423xxxxxxxxxxxx",
       "subscription": "planXX", // New OTA plan name
       "otastatus": "finished" // OTA progress: started, finished, error
   }
   

   Configuration Details

   Category	Item	Value	Remarks
   CONDITION	Execution condition	(Blank)
   CONFIG	URL	URL starting with https://hooks.slack.com/services	Refer to this method to obtain the webhook URL
   CONFIG	Payload
   OUTPUT	Send output to another channel	Disabled

   

Setup Steps

These are the steps to configure SORACOM Flux.

1. Select "Flux Apps" under "SORACOM Flux" from the hamburger menu.

   

2. Create a new Flux app by clicking "+ Create new Flux app".

   

3. Give it a suitable name.

   

4. Create a channel.

   

5. Select "API/Manual Execution".

   

6. Keep the default name and click "Next" and then "Create". In the event source settings of the resulting screen, click "+ Create Incoming Webhook".

   

7. Click "Create" with the default name. Once back on the previous screen, click "Show Webhook URL" and make a note of it.

   

8. Return to the Studio screen.

   

9. Click the gray pipe extending from the blue block and select the "Actions" tab.

   

10. Click "+ Add action". Select "SORACOM API" and click OK.

    

    Enter the following in the execution condition for the action:

    payload.otastatus == "finished"
    

11. Enter "setsimgroup" in the API search form under config and select "setSimGroup (Assign an IoT SIM to a SIM group)".

    

    Set the placeholder in the URL field to ${payload.simId}, ensuring the whole URL looks like this:

    /v1/sims/${payload.simId}/set_group
    

    For the HTTP body, set the destination group ID you noted earlier.

    {
        "groupId": "Destination Group ID"
    }
    

12. It should look like this:

    

13. Once you understand the precautions, check the box, select "Create new SAM", and click "Create" without enabling the output.

    

14. It should look like the following:

    

15. While this completes the basic setup, we will also set up Slack notifications to monitor progress and errors.

16. Create a Slack Incoming Webhook by referring to the following guide:

    https://users.soracom.io/ja-jp/guides/other-services/notifications/slack-app-incoming-webhook/

17. To make it parallel with the SORACOM API you just set up, click the gray pipe labeled "API Channel" extending from the trigger and select the "Actions" tab. Add the "Slack notification" action.

    

18. Once it looks like this, the setup is complete.

    

Event Handler Settings

Configure an event handler to trigger the SORACOM Flux flow you created in the previous step by calling the Webhook upon OTA completion. As explained at the beginning, the OTA of the subscription container is performed as an asynchronous process, so the event handler function must be used to monitor the completion of the OTA in a timely manner.

1. Set up the event handler.
   Select Event Handler from the hamburger menu.

   

2. Click + Create Event.

   

3. Name the event OTA_finished.
   (Following this, you will follow the same steps to create OTA_started and OTA_failed events.)
   The configuration details are as follows:

   Configuration Details

   Item	Field 1	Field 2	Field 3	Field 4	Remarks
   Target	Group	Select from the groups that appear when you enter the current group name	N/A	N/A	After selection, only the UUID will be shown. The point is that by setting a group as the target, the OTA status of all SIMs belonging to that group becomes monitored.
   Rule	Execute when a subscription is added to a SIM	Success	Do not re-evaluate
   Action	Action: Send a request to the specified URL	Execution timing: Execute immediately	Offset (minutes): 0	URL: Address starting with https://g.api.soracom.io/v1/flux/incoming_webhooks/	The URL is the Incoming Webhook URL from SORACOM Flux
   Action (cont.)	Method: POST	Content Type: Select application/json	HTTP Header key: (None)	HTTP Header value: (None)
   Action (cont.)	Body: {"imsi":"${imsi}","simId":"${simId}","subscription":"${subscription}","otastatus":"${otaStatus}"}

   Your settings should look like this:
   

4. Similarly, create events for "Failure" and "Started" statuses in the rule settings with the same configuration.

Executing the OTA

1. Schedule the OTA for the SIM in the pre-migration group.
   Following the standard procedure, select the target SIM from the "SIM Management screen" in the User Console.

   

2. Select "Add subscription" from the "Actions" menu.

   

3. Select the subscription (plan) to be added and click "Add subscription".
   

Finally, if the Flux settings are configured correctly, the group change will be performed at the moment the OTA is completed.