Mesh Firmware Migration API

This API only applies to CGRs running CG-OS software.

This chapter describes the Firmware Migration API:

■Using the Mesh Firmware Migration API

■Mesh Firmware Migration API Method Calls

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:

■cancelReprovision

■showReprovisionStatus

■startReprovisionByEidList

■startReprovisionByEidListAbridged

■startReprovisionByGroup

■startReprovisionByGroupAbridged

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

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

cancelReprovision Parameters describes the parameters in the interface.

Table 1 cancelReprovision Parameters
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.

cancelReprovision Results describes the parameters in the response.

Table 2 cancelReprovision Results
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

showReprovisionStatus Parameters describes the parameters in the interface.

Table 3 showReprovisionStatus Parameters
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.

showReprovisionStatus Results describes the parameters in the response.

Table 4 showReprovisionStatus Results
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.

showReprovisionStatus ReprovisionItemReport Results describes the parameters in the ReprovisionItemReport for the specified device.

Table 5 showReprovisionStatus ReprovisionItemReport Results
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.

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

startReprovisionByEidList Parameters describes the parameters in the interface.

Table 6 startReprovisionByEidList Parameters
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.

Note: The list is limited to a maximum of 1000 IP addresses. An error returns and the operation is not scheduled if more than 1000 are specified.

interfaceName

string

(For test purposes only.) The name of the interface involved in the action.

Note: Use the abridged calls for groups of mesh devices.

interfaceType

string

(For test purposes only.) The type of the interface involved in the action

Note: Use the abridged calls for groups of mesh devices.

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.

startReprovisionByEidList Results describes the parameters in the response.

Table 7 startReprovisionByEidList Results
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

startReprovisionByEidListAbridged Parameters describes the parameters in the interface.

Table 8 startReprovisionByEidListAbridged Parameters
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.

Note: The list is limited to a maximum of 1000 IP addresses. An error returns and the operation is not scheduled if more than 1000 are specified.

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.

startReprovisionByEidListAbridged Results describes the parameters in the response.

Table 9 startReprovisionByEidListAbridged Results
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

startReprovisionByGroup Parameters describes the parameters in the interface.

Table 10 startReprovisionByGroup Parameters
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.

startReprovisionByGroup Results describes the parameters in the response.

Table 11 startReprovisionByGroup Results
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

startReprovisionByGroupAbridged Parameters describes the parameters in the interface.

Table 12 startReprovisionByGroupAbridged Parameters
Parameter
Type
Description

action

string

Note: For mesh migration, this parameter is “Mesh Activation.”

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.

startReprovisionByGroupAbridged Results describes the parameters in the response.

Table 13 startReprovisionByGroupAbridged Results
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.