North Bound API User Guide for the Cisco IoT Field Network Director, Releases 3.x and 4.x
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- May 7, 2017
Chapter: Mesh Firmware Migration API
Mesh Firmware Migration API
 Note | This API only applies to CGRs running CG-OS software. |
This chapter describes the Firmware Migration API.
Using the Mesh Firmware Migration API
In your IoT FND NB API client application, use the following IoT FND server URL to access the Mesh Firmware Migration API WSDL:
http://<server_address> /nbapi/reprovision?wsdl
Mesh Firmware Migration API Method Calls
IoT FND allows you to update earlier versions of CGR firmware to allow Cisco mesh networking using the following APIs:
The mesh firmware migration process also requires editing of the Router Configuration and FAR Addition templates in IoT FND. See the IoT FND User Guide.
- cancelReprovision
- showReprovisionStatus
- startReprovisionByEidList
- startReprovisionByEidListAbridged
- startReprovisionByGroup
- startReprovisionByGroupAbridged
cancelReprovision
This call cancels a scheduled reprovisioning operation. Devices are queued in batches of 12 in FIFO order. As soon as the top reprovisioning operation completes, reprovisioning begins on the next device in the queue. When a reprovisioning operation is canceled, reprovisioning operations in progress complete. If the operation is scheduled for the future, then this call cancels the entire operation.
Prototype
cancelReprovision (String uid)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
|---|---|---|
|
uid |
string |
The UID of the scheduled reprovision operation. |
Results
If the uid parameter references an unknown UID, the UID of an operation in progress, or a UID of a device that completed the reprovisioning process, the resultStatus is FAILED, and an appropriate errorDetails message is set. If the resultStatus is SUCCESS, the operation was canceled and will not execute.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
string |
SUCCESS or FAILED. FAILED returns only on a bad UID. For all other results such as the UID of an operation in progress or UID of a device that completed the reprovisioning process, resultStatus is SUCCESS and the cancel operation did not run. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
showReprovisionStatus
This call retrieves the status of the reprovision operation correlating to the specified UID.
Prototype
showReprovisionStatus (String uid)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
|---|---|---|
|
uid |
string |
The UID of the scheduled reprovision operation. |
Results
ShowReprovisionStatusReport showReprovisionStatus(String uid)
A ShowReprovisionStatusReport always returns. resultStatus is ERROR if the UID does not reference a known operation, which happens if the UID was incorrect or if the UID referenced an operation that completed and was cleaned up by the automatic pruning logic. Data retention time defaults to 7 days after an operation completes, which is configurable in IoT FND.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
string |
SUCCESS or FAILED. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
|
uid |
string |
The UID of the reprovision operation correlating to this status. |
|
operationStatus |
string |
The ReprovisionOperationStatus value correlating to this operation. |
|
scheduledFor |
int |
Date specified in startReprovisionByEidList, startReprovisionByEidListAbridged, startReprovisionByGroup, or startReprovisionByGroupAbridged for operation execution. |
|
submittedAt |
int |
Date when this operation was submitted to startReprovisionByEidList. |
|
totalCount |
int |
Total number of devices specified in the list of EIDs in startReprovisionByEidList, startReprovisionByEidListAbridged, startReprovisionByGroup, or startReprovisionByGroupAbridged. |
|
processedAt |
int |
Date when the operation began. |
|
completedAt |
int |
Date when the operation finished processing all devices listed in startReprovisionByEidList, startReprovisionByEidListAbridged, startReprovisionByGroup, or startReprovisionByGroupAbridged if COMPLETED or FAILED; otherwise this parameter is null. |
|
successCount |
int |
Number of devices successfully processed. |
|
failedCount |
int |
Number of items that failed the processing operation. |
|
itemReports |
int |
List of ReprovisionItemReport objects. Each object defines the status for a single EID specified in startReprovisionByEidList, startReprovisionByEidListAbridged, startReprovisionByGroup, or startReprovisionByGroupAbridged. |
For a ShowReprovisionStatusReport object with an operationStatus of SCHEDULED or CANCELED, ReprovisionItemReport is null because no information is available for those objects until processing begins. For all other operationStatus values, a ReprovisionItemReport object will be returned for each EID that is to be processed.
The following table describes the parameters in the ReprovisionItemReport for the specified device.
|
Parameter |
Type |
Description |
|---|---|---|
|
eid |
int |
The EID of the device. |
|
itemStatus |
string |
The ReprovisionItemStatus value related to this device. |
|
errorDetails |
string |
Detailed error message if operationStatus is ERROR. |
|
processedAt |
int |
Date when the operation began. |
|
completedAt |
int |
Date when the operation finished processing the device. |
startReprovisionByEidList
This call is general for all reprovisioning actions, not just for mesh migration. Some input parameters are not applicable to mesh migration operations. This call schedules an operation to execute at a future date.
Note | For startReprovisionByEidList and startReprovisionByGroup, specify the interface name and interface type if all FARs have the same interface name and type. This is normally used for internal testing. |
Prototype
startReprovisionByEidList (String action, List<String> eidList, String interfaceName, String interfaceType, Date executionDate)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
||
|---|---|---|---|---|
|
action |
string |
The name of the reprovisioning action to run. For mesh migration, this is MESH_FIRMWARE_ACTIVATION. |
||
|
eidList |
string |
List of EIDs to perform the action on.
|
||
|
interfaceName |
string |
(For test purposes only.) The name of the interface involved in the action.
|
||
|
interfaceType |
string |
(For test purposes only.) The type of the interface involved in the action
|
||
|
executionDate |
date |
Date to execute the action. This is a required parameter. Specify the current time or a time in the past to execute immediately. |
Results
This method always returns a StartReprovisionReport object. If the operation failed to execute due to invalid parameters or if the EID list was determined invalid, FAILED returns. An operation is only scheduled and the UID returns if resultStatus is SUCCESS.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
int |
SUCCESS or FAILED. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
|
uid |
string |
The UID of the reprovision operation correlating to this status. |
startReprovisionByEidListAbridged
This call schedules an operation to execute at a future date.
Prototype
startReprovisionByEidListAbridged (String action, List<String> eidList, String interfaceName, String interfaceType, Date executionDate)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
||
|---|---|---|---|---|
|
action |
string |
The name of the reprovisioning action to run. For mesh migration, this is “Mesh Activation.” |
||
|
eidList |
string |
List of EIDs to perform the action on.
|
||
|
executionDate |
date |
Date to execute the action. This is a required parameter. Specify the current time or a time in the past to execute immediately. |
Results
This method always returns a StartReprovisionReport object. If the operation failed to execute due to invalid parameters or if the EID list was determined invalid, FAILED returns. An operation is only scheduled and the UID returns if resultStatus is SUCCESS.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
int |
SUCCESS or FAILED. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
|
uid |
string |
The UID of the reprovision operation correlating to this status. |
startReprovisionByGroup
This call executes the reprovisioning operation on the specified group.
Prototype
startReprovisionByGroup (String action, String groupName, String interfaceName, String interfaceType, Date executionDate)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
|---|---|---|
|
action |
string |
The name of the reprovisioning action to run. For mesh migration, this is “Mesh Activation.” |
|
groupName |
string |
The name of the tunnel provisioning group. |
|
executionDate |
date |
Date to execute the action. This is a required parameter. Specify the current time or a time in the past to execute immediately. |
Results
This method always returns a StartReprovisionReport object. If the operation failed to execute due to invalid parameters or if the EID list was determined invalid, FAILED returns. An operation is only scheduled and the UID returns if resultStatus is SUCCESS.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
int |
SUCCESS or FAILED. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
|
uid |
string |
The UID of the reprovision operation correlating to this status. |
startReprovisionByGroupAbridged
This call executes the reprovisioning operation on the specified group.
Prototype
startReprovisionByGroupAbridged (String action, String groupName, Date executionDate)
Parameters
The following table describes the parameters in the interface.
|
Parameter |
Type |
Description |
||
|---|---|---|---|---|
|
action |
string |
The name of the reprovisioning action to run. |
||
|
groupName |
string |
The name of the tunnel provisioning group. |
||
|
executionDate |
int |
Date to execute the action. This is a required parameter. Specify the current time or a time in the past to execute immediately. |
Results
This method always returns a StartReprovisionReport object. If the operation failed to execute due to invalid parameters or if the EID list was determined invalid, FAILED returns. An operation is only scheduled and the UID returns if resultStatus is SUCCESS.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
resultStatus |
int |
SUCCESS or FAILED. |
|
errorDetails |
string |
Error description if resultStatus is FAILED. |
|
uid |
string |
The UID of the reprovision operation correlating to this status. |
Feedback