All Collections
Developer 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 a week ago

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

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.

  • 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.

  • 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.

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
}
}

Did this answer your question?