Device Discovery and Import¶
Overview¶
This document describes the API usage of the ‘Device Discovery and Import Controller’ task. This task is used to discover and import BIG-IP device configurations into BIG-IQ.
REST Endpoint: /cm/global/tasks/device-discovery-import-controller¶
Requests¶
POST /cm/global/tasks/device-discovery-import-controller¶
Request Parameters¶
Name | Type | Required | Description |
---|---|---|---|
operationalMode | string | True | Specifies whether the new device is being imported or existing devices are being re-imported. |
deviceDetails | array_of_objects | True | List of devices and their import details. |
deviceReference | reference | False | Device reference to re-import already imported device configurations. |
link | string | True | URI link of the reference. |
newDevice | object | False | Device details to import a new device. |
address | string | True | IP address of the device to be imported. |
httpsPort | number | True | HTTPS port number to import a new device. |
userName | string | True | User name to authenticate device for import. |
password | string | True | Password to authenticate device for import. |
clusterName | string | False | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | False | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | False | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | True | List of modules to import. |
module | string | True | Module name to import for the device. |
properties | object | False | Additional properties provided for the import. |
cm:access:import-shared | boolean | False | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
conflictPolicy | string | True | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | False | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | False | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | False | Access group name to import Access configuration for devices. |
name | string | True | Name of the task. |
description | string | False | Description of the task. |
status | string | False | Current status of task. |
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported.. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
id | string | Id of the object. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a POST. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | No |
device_manager | No |
GET /cm/global/tasks/device-discovery-import-controller/<id>¶
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported.. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
id | string | Id of the object. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a GET. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | Yes |
device_manager | Yes |
DELETE /cm/global/tasks/device-discovery-import-controller/<id>¶
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
operationalMode | string | Specifies whether the new device is being imported or existing devices are being re-imported. |
deviceDetails | array_of_objects | List of devices and their import details. |
deviceReference | reference | Device reference to re-import already imported device’s configurations. |
link | string | URI link of the reference. |
newDevice | object | Device details to import a new device. |
address | string | IP address of the device to be imported. |
httpsPort | number | HTTPS port number to import a new device. |
userName | string | User name to authenticate device for import. |
password | string | Password to authenticate device for import. |
clusterName | string | Name of the HA cluster to which the device belongs. |
useBigiqSync | boolean | Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment. |
deployWhenDscChangesPending | boolean | Deploy when there are pending DSC changes on BIG-IP. |
moduleList | array_of_objects | List of modules to import. |
module | string | Module name to import for the device. |
status | string | Device import status. |
errorMsg | string | Error message if device import failed. |
startTime | string | Start time of module import for the device. |
endTime | string | End time of module import for the device. |
properties | object | Additional properties provided for the import.. |
cm:access:import-shared | boolean | When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’. |
taskReference | reference | Task reference. |
link | string | URI link of the reference. |
snapshotWorkingConfig | boolean | Snapshot module’s working configuration before import. |
deviceStatus | string | Import status of the device. |
trustTaskReference | reference | Device trust establishment task reference. |
link | string | URI link of the reference. |
superDiscoveryTaskReference | reference | Config discovery task reference. |
link | string | URI link of the reference. |
superImportTaskReference | reference | Configuration import task reference. |
link | string | URI link of the reference. |
messages | array_of_objects | List of messages gathered during different stages of the device import. |
msgType | string | Message severity level. |
msg | string | Message details. |
conflictPolicy | string | Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects. |
deviceConflictPolicy | string | Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects. |
snapshotWorkingConfig | boolean | Snapshot of the working configuration for all devices, before the import. |
accessGroupName | string | Access group name to import Access configuration for devices. |
currentStep | string | Current import step. |
startDateTime | string | Start date and time of task. |
name | string | Name of the task. |
errorMessage | string | Error message describing details of the task failure. |
description | string | Description of the task. |
id | string | Id of the object. |
endDateTime | string | End date and time of task. |
status | string | Current status of task. |
Error Response¶
HTTP/1.1 400 Bad Request
This response status is related to an error during a DELETE. A detailed error message displays in the response.
HTTP/1.1 401 Unauthorized
This response occurs when access is denied due to invalid credentials or insufficient permissions.
Permissions¶
Role | Allow |
---|---|
Trust_Discovery_Import | Yes |
Device_Viewer | No |
device_manager | No |
Examples¶
Create Device Discovery and Import Task¶
POST /cm/global/tasks/device-discovery-import-controller
{
"operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"newDevice": {
"address": "11.111.111.111",
"httpsPort": 443,
"userName": "admin",
"password": "password",
"clusterName": "cluster_1_data_center_1",
"useBigiqSync": false,
"deployWhenDscChangesPending": false
},
"moduleList": [{
"module": "adc_core",
"properties": {
"cm:access:import-shared": true
},
}],
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"accessGroupName": "DataCenter_1_AccessGroup",
"name": "task_for_xyz",
"description": "This task is to accomplish xyz.",
"status": "STARTED"
}
Response¶
HTTP/1.1 200 OK
{
"operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"newDevice": {
"address": "11.111.111.111",
"httpsPort": 443,
"userName": "admin",
"password": "password",
"clusterName": "cluster_1_data_center_1",
"useBigiqSync": false,
"deployWhenDscChangesPending": false
},
"moduleList": [{
"module": "adc_core",
"status": "STARTED",
"errorMsg": "Failed importing adc_core for device 11.111.111.111. Something bad happened.",
"startTime": "2018-01-30T21:37:10.104-0800",
"endTime": "2018-01-30T21:38:07.104-0800",
"properties": {
"cm:access:import-shared": true
},
"taskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"snapshotWorkingConfig": true
}],
"deviceStatus": "IMPORT_STAGE",
"trustTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superDiscoveryTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superImportTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"messages": [{
"msgType": "INFO",
"msg": "Importing adc_core for devie 11.111.111.111."
}]
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"accessGroupName": "DataCenter_1_AccessGroup",
"currentStep": "IMPORT_DEVICES",
"startDateTime": "2018-02-01T19:44:17.804-0800",
"name": "task_for_xyz",
"errorMessage": "Something bad happened at step 5.",
"description": "This task is to accomplish xyz.",
"id": "6287e999-9621-4e13-b588-51ca7895736e",
"endDateTime": "2018-02-01T19:44:17.804-0800",
"status": "STARTED"
}
Get Device Discovery and Import Task¶
GET /cm/global/tasks/device-discovery-import-controller/<id>
Response¶
HTTP/1.1 200 OK
{
"operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"newDevice": {
"address": "11.111.111.111",
"httpsPort": 443,
"userName": "admin",
"password": "password",
"clusterName": "cluster_1_data_center_1",
"useBigiqSync": false,
"deployWhenDscChangesPending": false
},
"moduleList": [{
"module": "adc_core",
"status": "STARTED",
"errorMsg": "Failed importing adc_core for device 11.111.111.111. Something bad happened.",
"startTime": "2018-01-30T21:37:10.104-0800",
"endTime": "2018-01-30T21:38:07.104-0800",
"properties": {
"cm:access:import-shared": true
},
"taskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"snapshotWorkingConfig": true
}],
"deviceStatus": "IMPORT_STAGE",
"trustTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superDiscoveryTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superImportTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"messages": [{
"msgType": "INFO",
"msg": "Importing adc_core for devie 11.111.111.111."
}]
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"accessGroupName": "DataCenter_1_AccessGroup",
"currentStep": "IMPORT_DEVICES",
"startDateTime": "2018-02-01T19:44:17.804-0800",
"name": "task_for_xyz",
"errorMessage": "Something bad happened at step 5.",
"description": "This task is to accomplish xyz.",
"id": "6287e999-9621-4e13-b588-51ca7895736e",
"endDateTime": "2018-02-01T19:44:17.804-0800",
"status": "STARTED"
}
Delete Device Discovery and Import Task¶
DELETE /cm/global/tasks/device-discovery-import-controller/<id>
Response¶
HTTP/1.1 200 OK
{
"operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
"deviceDetails": [{
"deviceReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"newDevice": {
"address": "11.111.111.111",
"httpsPort": 443,
"userName": "admin",
"password": "password",
"clusterName": "cluster_1_data_center_1",
"useBigiqSync": false,
"deployWhenDscChangesPending": false
},
"moduleList": [{
"module": "adc_core",
"status": "STARTED",
"errorMsg": "Failed importing adc_core for device 11.111.111.111. Something bad happened.",
"startTime": "2018-01-30T21:37:10.104-0800",
"endTime": "2018-01-30T21:38:07.104-0800",
"properties": {
"cm:access:import-shared": true
},
"taskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"snapshotWorkingConfig": true
}],
"deviceStatus": "IMPORT_STAGE",
"trustTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superDiscoveryTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"superImportTaskReference": {
"link": "https://localhost/mgmt/shared/foo/bar/866cfd8a-4d03-48e9-ba94-bb21a4bc2346"
},
"messages": [{
"msgType": "INFO",
"msg": "Importing adc_core for devie 11.111.111.111."
}]
}],
"conflictPolicy": "USE_BIGIP",
"deviceConflictPolicy": "USE_BIGIP",
"snapshotWorkingConfig": true,
"accessGroupName": "DataCenter_1_AccessGroup",
"currentStep": "IMPORT_DEVICES",
"startDateTime": "2018-02-01T19:44:17.804-0800",
"name": "task_for_xyz",
"errorMessage": "Something bad happened at step 5.",
"description": "This task is to accomplish xyz.",
"id": "6287e999-9621-4e13-b588-51ca7895736e",
"endDateTime": "2018-02-01T19:44:17.804-0800",
"status": "STARTED"
}