Device Management API: bulk operations via CSV/Excel file upload

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