API Feature Update: Last Session Info

Written by: Felix Hsieh Published: September 14, 2020 Services

Tags: API | Soracom | soracom product update

We are excited to announce that a number of our subscriber and SIM APIs will now include a previousSession< attribute! This attribute will make it easier to handle various SIM management tasks, especially if you have a large number of SIMs.

The sessionStatus Attribute

First, let’s take a look at the type of data that the subscriber or SIM API has always returned. If you use the getSubscriber API for a specific SIM, you normally get some data like this:

{
"operatorId": "OP0012345678",
"imsi": "295050012345678",
"iccid": "8942310000012345678",
"subscription": "plan01s",
"speedClass": "s1.standard",
"status": "active",
"sessionStatus": {
"gtpcTeid": 2062167075,
"lastUpdatedAt": 1599017317572,
"imei": "350000012345678",
"location": null,
"cell": {
"radioType": "lte",
"mcc": 440,
"mnc": 10,
"tac": 4728,
"eci": 49497861
},
"ueIpAddress": "10.123.45.67",
"dnsServers": [
"100.127.0.53",
"100.127.1.53"
],
"online": true
}
}

The sessionStatus attribute provides a lot of great information about the current status, such as:

• The IMEI of the device
• The cell ID where the device is connected to
• What type of network the device is using (LTE or 3G/GSM)
• The date time (timestamp) of the session

Different challenges at large scale

When you are managing only a few SIMs, you can just access the User Console and check each SIM’s session details directly. These details are helpful when you want to find out approximately where your SIM is located (by the cell ID), or check when the device last connected (by session timestamp).

However in many cases, as your number of SIMs grows, you will probably want to automate this process rather than checking each SIM one by one. You can take advantage of these details to help manage a large fleet of devices. For example:

• “We developed locally with just a few SIMs, but now we have 10,000 devices deployed all over the world.”
  By using the mcc (Mobile Country Code) attribute, you can group your SIMs by country. This can be useful if you are planning to make infrastructure changes and want to roll it out to your devices in stages instead of all at once.
• “We want to find which SIMs have been offline for a long time.”
  You can use the lastUpdatedAt attribute to find out if a SIM has not connected in a long time, in order to prepare a list of devices for field engineers to check, or set the SIM status to suspended to reduce costs.

As you can see, the sessionStatus attribute provides valuable information that is especially useful when you are developing scripts to manage your SIMs.

However, sessionStatus has one limitation: When a device is offline, the data will actually look like this:

"sessionStatus": {
"gtpcTeid": 0,
"lastUpdatedAt": 1520603586157,
"imei": null,
"location": null,
"ueIpAddress": null,
"dnsServers": null,
"online": false
},

Since the device is offline, there is no session, and therefore the details are all missing!

Up until now, to find the previous session details, you need to use the listSessionEvents or listSimSessionEvents API. Although these APIs will give you all of the same details, you can only query one SIM at a time. That means if you have 1,000 SIMs and half of them are offline, you need to make 500 additional API calls to find the previous session details for the SIMs that are currently offline!

Introducing the new previousSession attribute

With today’s update, the previous session details are now included in the listSims and listSubscribers APIs underneath a new previousSession attribute. This attribute will always contain the details of the last session, even if the SIM is offline. For example:

"sessionStatus": {
"gtpcTeid": 0,
"lastUpdatedAt": 1520603586157,
"imei": null,
"location": null,
"ueIpAddress": null,
"dnsServers": null,
"online": false
},
"previousSession": {
"gtpcTeid": 2062167075,
"imei": "350000012345678",
"cell": {
"radioType": "lte",
"mcc": 440,
"mnc": 10,
"tac": 4728,
"eci": 49497861
},
"ueIpAddress": "10.123.45.67",
"dnsServers": [
"100.127.0.53",
"100.127.1.53"
],
"createdTime": 1596606771678,
"deletedTime": 1596606814141
},

Since the listSims and listSubscribers APIs will return a list of all of your SIMs, you no longer need to check the previous session using a separate API for any SIMs that are offline!

The previousSession attribute will always contain the session details of the previous session:
• If the SIM is online, previousSession will correspond to the session before the current session
• If the SIM is offline, previousSession will correspond to the most recent session

Scripting is simpler and more powerful

You can take advantage of previousSession to build some powerful automations. For example, when using the Soracom CLI:

soracom subscribers list --fetch-all | jq -r '.[] | select(.previousSession.cell.mcc == 310) | [.iccid, .imsi, .previousSession.imei] | @csv'

This convenient one-liner will fetch all SIMs in your Soracom account that most recently connected in the US, and generates a CSV output of their ICCID, IMSI, and IMEI.

Of course, this is just a quick example of what you can do with this new attribute. We’re excited to see how you use this feature to improve your SIM management tasks!