Skip to main content
All CollectionsDeveloper Documentation
Device Management API: bulk operations via CSV file upload
Device Management API: bulk operations via CSV file upload

Bulk operations for device activation and device group assignment

Team Celona avatar
Written by Team Celona
Updated over 9 months ago

This document provides a detailed step-by-step description of how to use the Bulk Device Activation and Device Group Assignment API

API Endpoint: /v1/api/hss/activation-from-file

The API accepts a CSV file containing device information and a specific operation code [op_code] based on the intended use case.

Device Activation and Device Group Assignment

  • Mandatory - ICCID

    • Activation will fail if ICCID is not specified

  • Optional - DEVICE_NAME & DEVICE_GROUP

    • The device name will be applied only for the ICCIDs which succeeded in device activation.

    • The device is assigned to the default device group if no DEVICE_GROUP is specified.

  • Following optional fields are available to support sim lock configurations for each device:

    • Optional - SimLockStatus

      • string

      • Enabled” for enabling sim lock

      • Disabled” or ““ for disabling sim lock

    • Optional - SimLockPolicy

      • string

      • "ONATTACH"

      • "IMEIMAPPING"

    • Optional - SimLockExpectedIMEI

      • string

      • IMEI if IMEIMAPPING has been set as SimLockPolicy

  • Op Code: ACTIVATE_AND_DG_ASSIGN

  • Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

Device Activation

  • Mandatory - ICCID

    • Activation will fail if ICCID is not specified.

  • Optional - DEVICE_NAME

    • The device name will be applied only for the ICCIDs which succeeded in device activation.

  • Following optional fields are available to support sim lock configurations for each device:

    • Optional - SIMLOCKSTATUS

      • string

      • Enabled” for enabling sim lock

      • Disabled” or ““ for disabling sim lock

    • Optional - SIMLOCKPOLICY

      • string

      • "ONATTACH"

      • "IMEIMAPPING"

    • Optional - SIMLOCKEXPECTEDIMEI

      • string

      • IMEI if IMEIMAPPING has been set as SimLockPolicy

  • Op Code: ACTIVATE

  • Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

Device Group Assignment

  • Mandatory - ICCID

  • Optional - DEVICE_GROUP (name of the device group)

    • The device is assigned to the default device group if no DEVICE_GROUP is specified.

  • Op Code: DG_ASSIGN

  • Note - Starting with 2311, CLUSTER_NAME in the CSV will be ignored because of the change in device activation workflow. Device and Edge cluster association is now defined by the network control policy(s) of the device group to which the device belongs

The API also handles failure causes without defaulting to ‘fail for all,’ which means:

  • devices with valid ICCIDs will proceed with the operation

  • devices with invalid ICCIDs will be added to the failed list of devices and displayed as part of the failure response.

    Note

  • CSV parsing is position based, hence it is expected that the order specified above is strictly followed.

  • Sim lock fields above are optional and don’t have to be provided.

  • If sim lock fields are not provided, the device will be activated with sim lock disabled.

API call example

curl --location 'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<Operation Code>'  
--header 'Content-Type: multipart/form-data; boundary=<calculated when request is sent>' --header 'x-api-key: ‘<API_KEY>’
--header 'Accept: */*' --form 'simDataFile=@"/<path_to_file>/act_data.csv"'

API Sample Response for successful device activation and device group assignment

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE_AND_DG_ASSIGN 

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003477,Cluster123,Tom's Macbook,TestDeviceGroup
89105212033100003478,Cluster123,Jane's iPhone,TestDeviceGroup
89105212033100003479,Cluster123,Dan's iPad,TestDeviceGroup

Response:

{ 
"data": {
"failed_devices": null,
"successful_devices": [
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"89105212033100003477",
"89105212033100003478",
"89105212033100003479"
]
},
{
“action”: “DEVICE_NAME_UPDATE”,
“iccids”: [
“89105212033100003474”,
“89105212033100003476”
]
},
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003477",
"89105212033100003478",
"89105212033100003479"
]
}
]
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}

API Sample Response for successful device activation

Request :

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003474,Cluster123,Tom's Macbook,TestDeviceGroup
89105212033100003475,Cluster123,Jane's iPhone,TestDeviceGroup
89105212033100003476,Cluster123,Dan's iPad,TestDeviceGroup

Response:

{ 
“data”: {
“failed_devices”: null,
“successful_devices”: [
{
“action”: “DEVICE_ACTIVATION”,
“iccids”: [
“89105212033100003474”,
“89105212033100003475”,
“89105212033100003476”
]
},
{
“action”: “DEVICE_NAME_UPDATE”,
“iccids”: [
“89105212033100003474”,
“89105212033100003476”
]
}
]
},
“responseMeta”: {
“code”: 200,
“error”: “”,
“success”: true
}
}

Successful Device Group Assignment -

Request :

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=DG_ASSIGN 

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_GROUP 
89105212033100003474,Cluster123,TestDeviceGroup
89105212033100003475,Cluster123,TestDeviceGroup
89105212033100003476,Cluster123,TestDeviceGroup

Response:

{ 
"data": {
"failed_devices": null,
"successful_devices": [
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003474",
"89105212033100003475",
"89105212033100003476"
]
}
]
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}
}

API Sample Responses for failures

Mismatched Columns - CSV File Errors (FILE_IO) -

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<any_op_code> 

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP
891052120331000034772305,Cluster123,Tom’s iPhone,TestDeviceGroup

Response:

{ 
"data": {
"failed_devices": [
{
"action": "FILE_IO",
"file_records": [
"89105212033100003477Cluster123 TestDeviceGroup"
],
"reason": "Corrupted Record"
}
],
"successful_devices": null
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}
}

Duplicate ICCID Records - CSV File Errors (FILE_IO)

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=<any_op_code>  

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP 
89105212033100003481,Cluster123,Jane's iPad,TestDeviceGroup
89105212033100003481,Cluster123,Jane's iPad,TestDeviceGroup

Response:

{ 
"data": {
"failed_devices": [
{
"action": "FILE_IO",
"file_records": [
"89105212033100003481 Cluster123 TestDeviceGroup"
],
"reason": "Duplicate ICCID records in the CSV, 1st occurrence has been processed"
}
],
"successful_devices": [
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"89105212033100003481"
]
},
{
"action": "DEVICE_NAME_UPDATE",
"iccids": [
"89105212033100003481"
]
},
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003481"
]
}
]
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}
}

Various Errors in Device Activation

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=ACTIVATE 

Input CSV File :

ICCID,CLUSTER_NAME,DEVICE_NAME,DEVICE_GROUP
89105212033100003483,2305test123,Bob’s Device 1,TestDeviceGroup
89105212033100003484,,Bob’s Device 2,TestDeviceGroup
89105212033100003485,Cluster123,Bob’s Device 3,TestDeviceGroup
89105212033100003486,Cluster123,Bob’s Device 4,TestDeviceGroup
90102315010999901130,Cluster123,Bob’s Device 5,TestDeviceGroup
90105212033100000244,Cluster123,Bob’s Device 6,TestDeviceGroup

Errors in the above ICCID Inputs:

  • 89105212033100003486 – Invalid/Not existing ICCID Record

  • 90105212033100000244 – ICCID not into the provisioned state

Successful API Response:

  • 89105212033100003485 – This is a valid ICCID

Response:

{ 
"data": {
"failed_devices": [
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"89105212033100003486"
],
"reason": "No IMSI records found for the given ICCIDs"
},
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"90105212033100000244"
],
"reason": "ICCID status needs to be 'Provisioned' for activation, following ICCIDs are not provisioned"
}
],
"successful_devices": [
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"89105212033100003485"
]
}
]
{
"action": "DEVICE_NAME_UPDATE",
"iccids": [
"89105212033100003485"
]
}
]
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}
}

Errors in Device Group Assignment

Request:

'https://api.celona.io/v1/api/hss/activation-from-file?customer_id=<customer_id>&op_code=DG_ASSIGN

Input CSV File:

ICCID,CLUSTER_NAME,DEVICE_NAME
89105212033100003497,Cluster123,,
89105212033100003498,Cluster123,,
89105212033100003500,Cluster123,,
89105212033100000193,Cluster123,,TestDeviceGroup

Errors in above ICCID Inputs:

  • 89105212033100000193 – Devices already assigned to a Device Group

  • 89105212033100003498 – Invalid Device Group

  • 89105212033100003500 – Invalid/Not existing ICCID Record

Successful API Response:

  • 89105212033100003497 – Valid Record

Response:

{ 
"data": {
"failed_devices": [
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100000193"
],
"reason": "Devices already are assigned to a Device Group, please reassign them first"
},
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003500"
],
"reason": "No IMSI records found for the given ICCIDs"
},
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003498"
],
"reason": "Device group: new1 doesn't exist"
}
],
"successful_devices": [
{
"action": "DEVICE_GROUP_ASSIGNMENT",
"iccids": [
"89105212033100003497"
]
}
]
},
"responseMeta": {
"code": 200,
"error": "",
"success": true
}
}

Additional Examples with SIM lock parameters

Example 1

ICCID,CLUSTERNAME,DEVICENAME,DEVICEGROUPNAME,SIMLOCKSTATUS,SIMLOCKPOLICY,SIMLOCKEXPECTEDIMEI 
89105212033100003500,,DeviceTest1,,Enabled,ONATTACH, 89105212033100003501,,DeviceTest2,,Disabled,, 89105212033100003502,,,,Enabled,IMEIMAPPING,123456789012345
  • SIM lock will be enabled on attach for 89105212033100003500. Even though SIMLOCKEXPECTEDIMEI is not relevant for ONATTACH policy, it still has to be provided for the CSV record as at least one of the optional SIM lock parameters were specified.

  • SIM lock will be disabled for 89105212033100003501. Even though SIMLOCKPOLICY and SIMLOCKEXPECTEDIMEI are not relevant when SIM lock is disabled, they still have to be provided for the CSV record as at least one of the optional sim lock parameters were specified.

SIM lock will be enabled with IMEI mapping for 89105212033100003502. All the SIM lock fields are provided here. ClusterName and DeviceName are omitted from the record and are specified with ,,

Example 2

ICCID,ClusterName,DeviceName,DeviceGroupName 89105212033100003500,,DeviceTest1, 89105212033100003501,,,DeviceGroup1
  • The optional SIM lock fields are not provided for these two records. If the op_code provided for this is ACTIVATE, then devices will be activated with SIM lock disabled.

Sim Lock Related CSV Validations

As part of the response of the CSV file API request, a list of failed and successful devices are reported. Based on the optional sim lock fields that are added, there are a few more validations and errors that might be seen for a device. These errors are listed below:

InvalidSimLockEntries:

  • Sample Response

  • Reason: Invalid Sim Lock Params, all sim lock fields must be specified and valid. SimLockStatus must be Enabled/Disabled, SimLockPolicy should be IMEIMAPPING/ONATTACH when enabled, SimLockExpectedIMEI should be empty for IMEIMAPPING and must be specified for ONATTACH

  • Resolution: Fix the record based on the instructions provided in the message

SimLockUnsupportedEntries:

  • Sample Response

  • Reason: Sim Lock configurations are not supported when GROUPBASEDDEVICEACTIVATION and NEWIPDOMAINWORKFLOW flags are disabled. SimLockStatus should be Disabled or left empty

  • Resolution: Fix the record based on the instructions provided in the message

DEFAULTLOCKONACTIVATION

  • Sample Response

  • Reason: DEFAULTLOCKONACTIVATION flag is enabled for the customer which means that all the devices are required to be locked during activation.

  • Resolution: Fix the record by enabling sim lock and adding in a policy for the record

Did this answer your question?