All Collections
Developer Documentation
Device Management API: bulk operations via CSV/Excel file upload
Device Management API: bulk operations via CSV/Excel 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 & CLUSTER_NAME

    • Activation will fail if ICCID or CLUSTER_NAME 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

Device Activation

  • Mandatory - ICCID & CLUSTER_NAME

    • Activation will fail if ICCID or CLUSTER_NAME is not specified.

  • Optional - DEVICE_NAME

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

  • Op Code: ACTIVATE

Device Group Assignment

  • Mandatory - ICCID

  • Optional - CLUSTER_NAME (name of Edge Cluster assigned)

  • 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

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:

  • 89105212033100003484 – Edge Cluster ID = NULL

  • 89105212033100003483 – Incorrect Edge Cluster Name

  • 90102315010999901130 – ICCIDs previously assigned to another Edge Cluster than in the request

  • 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": [
"89105212033100003484"
],
"reason": "Edge Cluster Name parameter is required and is missing for the ICCIDs - 89105212033100003484"
},
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"89105212033100003483"
],
"reason": "Invalid Edge Cluster - PSE Cluster: 2305test123 not found for customer: 10000"
},
{
"action": "DEVICE_ACTIVATION",
"iccids": [
"90102315010999901130"
],
"reason": "ICCIDs were previously activated on another Edge Cluster"
},
{
"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?