Groups

Basic Usage

Basic Group operations are very simple. Groups are deeply integrated with the Soracom User Console, ensuring that creating a Group and managing its options is easy to access. While Groups can be accessed from several parts of the User Console, the following examples show basic usage from the Soracom Air for Cellular screens.

Managing Groups

Creating a Group

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

  2. If this is your first group, click the Create a group button. If not, click the Add button.

    https://console.soracom.io

    Add Group

  3. Enter a name for your group, then click Create.

    Create Group

When you create a new group, it will automatically be assigned an ID. This ID is required when performing actions to the group using the Soracom API or Soracom CLI.

You can also create a group when registering a new SIM, or when adding a device to a group.

Renaming a Group

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

  2. From the list of groups, click the name of the group you want to rename to open its settings page.

    https://console.soracom.io

    Group Details

  3. From the group settings page, click the icon next to the current group name.

    https://console.soracom.io

    Rename Group

  4. Enter the new name for your group, then click Save.

Deleting a Group

A group can only be deleted if there are no devices attached to the group. If your group contains any devices, remove them from the group first.

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

  2. From the list of groups, click the name of the group you want to delete to open its settings page.

    https://console.soracom.io

    Group Details

  3. From the group settings page, click the Advanced settings tab.

  4. Click the Delete this group panel to expand its options, then click Delete this group.

    https://console.soracom.io

    Delete Group

  5. A warning will appear asking you to confirm deletion.

Managing Devices

The following instructions are for Air for Cellular devices, but also apply to Air for Sigfox, Air for LoRaWAN, and Soracom Inventory devices. Simply open the Sigfox Devices, LoRa Devices, or Device Management screens respectively.

Adding a Device to a Group

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to modify.

  3. Click the Actions menu, then select Change group.

    https://console.soracom.io

    Change Group

  4. From the Update selected subscribers group dialog, select the group you want to set for the IoT SIM device, then click Change Group.

    Select Group

    You can also create a new group by selecting the Create group... option.

Removing a Device from a Group

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to modify.

  3. Click the Actions menu, then select Change group.

    https://console.soracom.io

    Change Group

  4. From the Update selected subscribers group dialog, select Unset group, then click Change Group.

    Unset Group

Programmatic Usage

You can manage Groups programmatically using the Soracom API or Soracom CLI.

In addition to create, rename, delete, add, and remove actions, the API and CLI provides the ability to list subscribers in each group, as well as configure various group parameters. Refer to the API reference or CLI documentation for further information.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the createGroup API to create a group:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "tags": {
>          "name": "my-group"
>        }
>      }' \
>  https://g.api.soracom.io/v1/groups

Once the group is created, the API will return a response which includes the group ID. You can then use this ID for additional group-related APIs.

A group's name is stored in the name attribute of its tags. To rename a group, simply update its tags using the putGroupTags API:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '[
>        {
>          "tagName": "name",
>          "tagValue": "my-new-group"
>        }
>      ]' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>/tags

To delete the group, use the deleteGroup API:

curl -X DELETE \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>

To add an IoT SIM to a group, use the Subscriber setGroup API:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "groupId": "<GROUP-ID>"
>      }' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/set_group

And to remove it from a group, use the Subscriber unsetGroup API:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/unset_group

Groups for Sigfox, LoRaWAN, and Soracom Inventory devices are managed similarly using the following API methods:

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, use the groups create command to create a group:

soracom groups create --body '{ "tags": { "name": "my-group" } }' --coverage-type g

Once the group is created, the CLI will return a response which includes the group ID. You can then use this ID for additional group-related commands.

Similar to the API example above, we can update a group's tags with the groups put-tags command in order to rename it:

soracom groups put-tags --group-id '<GROUP-ID>' --body '[ { "tagName": "name", "tagValue": "my-new-group" } ]' --coverage-type g

To delete the group, use the groups delete command:

soracom groups delete --group-id '<GROUP-ID>' --coverage-type g

To add an IoT SIM to a group, use the subscribers set-group command:

soracom subscribers set-group --imsi '<IMSI>' --group-id '<GROUP-ID>' --coverage-type g

And to remove it from a group, use the subscribers unset-group command:

soracom subscribers unset-group --imsi '<IMSI>' --coverage-type g

Groups for Sigfox, LoRaWAN, and Soracom Inventory devices are managed similarly using the following commands:

  • soracom sigfox-devices set-group and soracom sigfox-devices unset-group
  • soracom lora-devices set-group and soracom lora-devices unset-group
  • soracom devices set-group and soracom devices unset-group

Metadata Service

The Metadata Service allows an Air SIM device to access and configure its own settings without the need for authentication. For more information, refer to the Metadata Service documentation.

When the Metadata Service is enabled, an Air for Cellular device can set or unset its own group configuration.

Use the Subscriber setGroup API to assign the IoT SIM to a group:

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "groupId": "<GROUP-ID>"
>      }' \
>  http://metadata.soracom.io/v1/subscriber/set_group

And to remove it from a group, use the Subscriber unsetGroup API:

curl -X POST \
>  http://metadata.soracom.io/v1/subscriber/unset_group

When changing an IoT SIM's group assignment, not all options will take effect immediately. Your device may need to disconnect from the network and reconnect in order to load settings from a new group assignment.