Device Management API

This chapter describes the Device Management API.

Using the Device Management API

In your IoT FND NB API client application, use this IoT FND server URL to access the Device API WSDL:

http://<server_address> /nbapi/device?wsdl

Using the device-client Script

The IoT FND distribution provides a Device Management API client (device-client script) in the cgms-tools-version .x86_64.rpm package. The client is wrapped by a shell script (/opt/cgms-tools/bin/device-client) to directly communicate with the IoT FND API.

[root@localhost bin]# ./device-client
 
usage:
    ./bin/device-client add <endpoint URL> <filename>
    ./bin/device-client remove <endpoint URL> <filename>
    ./bin/device-client set <endpoint URL> <filename> <status>
    ./bin/device-client update <endpoint URL> <filename>
    ./bin/device-client export <endpoint URL> <query>
    ./bin/device-client job <endpoint URL> <job id>

The following table lists device-client script commands:

Table 1 device-client Commands

Command

Description

add

Calls the addDevices API.

remove

Calls the removeDevices API.

set

Calls the setDevices API to change status.

update

Calls the updateDevices API to change device properties.

export

Calls the exportDevices API.

job

Calls the getJob API to get the status of the job for one of the commands above.

Except for export and job, all other commands return a job ID used to query the job execution status.

Device Management API Method Calls

addDevices

This call lets the client add the devices specified in a CSV file to a managed device list in the IoT FND database. It is an asynchronous call that returns a job ID used to query the status of the add device job using the getJob call (see getJob).

Prototype

	<dev:addDevices
>
		<file
>
		<data
>eid:564620131674</data>
		<filename
>H:\SGBU\csv_loading\test_for_device_api_2.csv</filename>
		<username
>root</username>
		</file>
	</dev:addDevices>

Parameters

The following table describes the parameters in the interface.

Table 2 addDevices Parameters

Parameter

Options

Description

file

data

filename

username

A structure describing the CSV file to import. This file contains the list and details of devices to add. The data type is base 64 binary.

This example CSV file specifies new values for the mapLevel, latitude, and longitude properties of the specified devices:

eid,mapLevel,lat,lng
CA06001400100,2,-22.229488,37.860659 CA06001400100-0,15,-22.22887230524572,37.85273990917842 CA06001400100-1,15,-22.21759741145942,37.85962556788922

Results

The following table describes the parameters in the response.

Table 3 addDevices Response

Parameter

Type

Description

jobId

int

Use the job ID to get more information about the status of this call. For more information, see getJob.

addDevice SOAP XML Request Format

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://devicemgmt.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:addDevices>
         <!--Optional:-->
         <file>
            <!--Optional:-->
            <data>eid:564620131674</data>
            <!--Optional:-->
            <filename>H:\SGBU\csv_loading\test_for_device_api_2.csv</filename>
            <!--Optional:-->
            <username>root</username>
         </file>
      </dev:addDevices>
   </soapenv:Body>
</soapenv:Envelope>

removeDevices

This call lets the client remove the devices specified in a CSV file from a managed devices list stored in the IoT FND database. It is an asynchronous call that returns a job ID used to query the status of this job using the getJob call (see getJob).

Prototype

	<dev:removeDevices
>
		<file
>
		<data
>eid:136162421901</data>
		<filename
>h:\SGBU|csv_loading\remove_device_Notepad_format.csv</filename>
		<
username
>root</username>
		</file>
	</dev:removeDevices>

Parameters

The following table describes the parameters in the interface.

Table 4 removeDevices Parameters

Parameter

Options

Description

file

data

filename

username

A structure describing the CSV file to import. This file contains the list of devices to remove. The data type is base 64 binary.

This example CSV file specifies new values for the mapLevel, latitude, and longitude properties of the specified devices:

eid,mapLevel,lat,lng
CA06001400100,2,-22.229488,37.860659 CA06001400100-0,15,-22.22887230524572,37.85273990917842 CA06001400100-1,15,-22.21759741145942,37.85962556788922

Results

The following table describes the parameters in the response.

Table 5 removeDevices Response

Parameter

Type

Description

jobId

int

The job ID used to get more information about the status of this call. For more information, see getJob.

removeDevices SOAP XML Request Format

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://devicemgmt.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:removeDevices>
         <!--Optional:-->
         <file>
            <!--Optional:-->
            <data>eid:136162421901</data>
            <!--Optional:-->
            <filename>h:\SGBU|csv_loading\remove_device_Notepad_format.csv</filename>
            <!--Optional:-->
            <username>root</username>
         </file>
      </dev:removeDevices>
   </soapenv:Body>
</soapenv:Envelope>

setDevices

This call sets the properties of the specified devices as defined in a CSV file.

Parameters

The following table describes the parameters in the interface.

Table 6 setDevices Parameters

Parameter

Options

Description

file

data

filename

username

A structure describing the CSV file to import. This file contains the list of devices and corresponding properties to set. The data type is base 64 binary.

This example CSV file specifies new values for the mapLevel, latitude, and longitude properties of the specified devices:

eid,mapLevel,lat,lng
CA06001400100,2,-22.229488,37.860659 CA06001400100-0,15,-22.22887230524572,37.85273990917842 CA06001400100-1,15,-22.21759741145942,37.85962556788922

Results

The following table describes the parameters in the response.

Table 7 setDevices Response

Parameter

Type

Description

jobId

int

The job ID used to get more information about the status of this call. For more information, see getJob.

updateDevices

This call updates the properties of the specified devices with new values provided in CSV file.

Prototype

	<dev:updateDevices
>
		<file
>
		<data
>eid:568127286335</data>
		<filename
>?</filename>
		<username
>?</username>
		</file>
	</dev:updateDevices>

Parameters

The following table describes the parameters in the interface.

Table 8 updateDevice Parameters

Parameter

Type

Description

file

data

filename

username

This structure describes the CSV file to import. This file contains the list of devices and corresponding properties to update. The data type is base 64 binary.

This example CSV file specifies new values for the mapLevel, latitude, and longitude properties of the specified devices:

eid,mapLevel,lat,lng CA06001400100,2,-22.229488,37.860659CA06001400100-0,15,-22.22887230524572,37.85273990917842CA06001400100-1,15,-22.21759741145942,37.85962556788922CA06001400100-10,15,-22.21672330007085,37.85933754140877CA06001400100-100,15,-22.22737656792707,37.866319080937444CA06001400100-1000,15,-22.23107565852129,37.86334942264521CA06001400100-1001,15,-22.2344480993644,37.86209437189405

Results

The following table describes the parameters in the response.

Table 9 updateDevice Response

Parameter

Type

Description

jobId

int

The job ID used to get more information about the status of this call. For more information, see getJob.

updateDevice SOAP XML Request Format

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://devicemgmt.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:updateDevices>
         <!--Optional:-->
         <file>
            <!--Optional:-->
            <data>eid:568127286335</data>
            <!--Optional:-->
            <filename>?</filename>
            <!--Optional:-->
            <username>?</username>
         </file>
      </dev:updateDevices>
   </soapenv:Body>
</soapenv:Envelope>

exportDevices

This call returns a list of devices found by the query. This is an asynchronous call. Unlike other device management APIs, this call is blocking until all results are consumed by the caller.

Prototype

	<dev:exportDevices
>
		<username
>root</username>
		<query
>cgr1000</query>
	</dev:exportDevices>

Parameters

The following table describes the parameters in the interface.

Table 10 exportDevices Parameters

Parameter

Type

Description

username

string

IoT FND username used as part of the job creation.

query

string

The query that determines the criteria of the devices to export.

Results

The following table describes the parameters in the response.

Table 11 exportDevices Response

Parameter

Type

Description

data

base64Binary

The job ID used to get more information about the status of this call. For more information, see getJob.

date

dateTime

The date of the query (UTC time).

query

string

The query used to find the devices to export.

status

string

Status of the job.

exportDevices SOAP XML Request Format

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://devicemgmt.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:exportDevices>
         <!--Optional:-->
         <username>root</username>
         <!--Optional:-->
         <query>cgr1000</query>
      </dev:exportDevices>
   </soapenv:Body>
</soapenv:Envelope>

getJob

This call returns a job report describing the detailed execution status of the specified job.

Prototype

	<dev:getJob
>
         <jobId
>110</jobId>
	</dev:getJob>

Parameters

The following table describes the parameters in the interface.

Table 12 getJob Parameters

Parameter

Type

Description

jobId

int

The job ID to return information about.

Results

The following table describes the parameters in the response.

Table 13 getJob Results

Parameter

Type

Description

id

integer

Job ID.

username

string

The username of the job submitter.

filename

string

The filename of the job.

type

string

The job type.

totalCount

integer

Total count includes successes and failures.

successCount

integer

Success count represents the number of devices successfully updated.

failureCount

integer

Failure count summarizes the number of devices not successfully updated.

status

string

The job execution status.

submittedAt

date

The job submission date (UTC time).

updatedAt

date

The job updating date (UTC time).

logs

string

The logged messages of the job execution.

exportJob SOAP XML Request Format

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://devicemgmt.nbapi.cgms.cisco.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:getJob>
         <jobId>110</jobId>
      </dev:getJob>
   </soapenv:Body>
</soapenv:Envelope>