Device Import¶
Overview¶
Use the Device Import API to create a super-task to import copies of multiple module objects from the BIG-IQ’s current-config to the BIG-IQ’s working-config. To import multiple modules, send a POST request to the device-import task collection on the BIG-IQ. Specify the modules of interest in moduleList (firewall, security_shared, asm, adc_core, access, dns, fps or sslo). The API’s response can include the status for the super-task and for each individual module because the system runs a separate import task for each module. If the required LTM (ADC) module is missing the entire super-task fails. Missing any other module does not cause failure and the super-task continues to import the specified modules. Use the Device RMA API to remove module objects from the BIG-IQ’s working-config. Use the Device Discovery API to determine what module objects exist on a single BIG-IP and then create corresponding copies of these module objects in the BIG-IQ’s current-config.
REST Endpoint: mgmt/cm/global/tasks/device-import¶
Requests¶
To create a super-task which can import multiple module objects from the BIG-IQ’s current-config to the BIG-IQ’s working-config, send a POST request to the device-import endpoint.
POST mgmt/cm/global/tasks/device-import¶
Request Parameters¶
The JSON in the body of the POST request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
conflictPolicy | string | False | Conflict resolution policy for shared objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. A conflict arises if the imported module object already exists in the working-config and the copy in the current-config and working-config are different. If no conflict resolution policy has been specified, then the task can pause in the PENDING_CONFLICT step to allow the client to fill in a per-object resolution. |
description | string | False | An optional description for the super-task. |
deviceConflictPolicy | string | False | Conflict resolution policy for device-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. A conflict arises if the imported module object already exists in the working-config and the copy in the current-config and working-config are different. If no conflict resolution policy has been specified, then the task can pause in the PENDING_CONFLICT step to allow the client to fill in a per-object resolution. |
deviceReference | object | True | The value of deviceReference is a link object for the BIG-IP targeted by this import request. |
link | string | True | URL of deviceReference |
failOnConflict | boolean | False | If failOnConflict is true and there are import conflicts, the module import fails and the conflict is unresolved. |
moduleList | object array | True | A list identifying the module objects to remove. The status fields of the module objects are not required in the POST request. Provide the module object identifier in module. |
module | string | True | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
properties | object | False | Module-specific properties. |
snapshotWorkingConfig | boolean | False | True if a module snapshot should be created before import. |
name | string | False | An optional name for the super-task. |
skipClusterSync | boolean | False | If skipClusterSync is true, skip cluster synchronization for clustered devices. |
versionedConflictPolicy | string | False | Conflict resolution policy for version-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. A conflict arises if the imported module object already exists in the working-config and the copies in the current-config and working-config are different. If no conflict resolution policy has been specified, then the task can pause in the PENDING_CONFLICT step to allow the client to fill in a per-object resolution. |
Query Parameters¶
None
Response¶
The JSON in the body of the POST response can contain the following parameters. The super-task’s status in the initial response to the POST request can be “STARTED”, and to poll for the updated status you can send repeated GET requests to the selfLink of the task. The moduleList in the response to POST or GET can also contain information about the status of each individual module.
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the import task. |
allModuleStatus | object | Accumulated list of imported modules and status, whether being imported in this run or previously imported. Format same as moduleList. |
conflictPolicy | string | Conflict resolution policy for shared objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
currentStep | string | Current step of the import task. Possible values: “INIT”, “GET_DEVICE_IN_GROUPS”, “CHECK_EXISTING_TASKS”, “DELETE_MODULE_TASKS”, “PROCESS_MODULE_TASKS” or “DONE”. |
description | string | An optional description for the task. |
deviceConflictPolicy | string | Conflict resolution policy for device-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
deviceReference | object | The value of deviceReference is a link object for the BIG-IP targeted by this import request. |
link | string | URL of deviceReference |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not FAILED. |
failOnConflict | boolean | If failOnConflict is true and there are import conflicts, fail module import and do not resolve them. |
id | string | The id of the task. |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
moduleList | object | List of modules being imported, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module import task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
properties | object | Module-specific properties. |
snapshotWorkingConfig | boolean | True if a module snapshot should be created before import. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module-specific task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module import task was already active. |
taskReference | string | Reference to module import task. |
link | string | URL of the reference to module import task. |
name | string | An optional name for the task. |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
selfLink | string | The URL to access this item directly. |
skipClusterSync | boolean | If skipClusterSync is true, skip cluster synchronization for clustered devices. |
startDateTime | string | The time the task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
username | string | The user that initiated the task. |
versionedConflictPolicy | string | Conflict resolution policy for version-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
GET /cm/global/tasks/device-import/<id>¶
To check the status of a super-task you can send a GET request to the endpoint and specify the super-task’s id. The super-task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the super-task. The status of the individual module tasks are returned in moduleList.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
Name | Type | Description |
---|---|---|
ItemState | object | State of the import task |
ItemState | object | State of the import task. |
allModuleStatus | object | Accumulated list of imported modules and status, whether being imported in this run or previously imported. Format same as moduleList. |
conflictPolicy | string | Conflict resolution policy for shared objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
currentStep | string | Current step of the import task. Possible values: “INIT”, “GET_DEVICE_IN_GROUPS”, “CHECK_EXISTING_TASKS”, “DELETE_MODULE_TASKS”, “PROCESS_MODULE_TASKS” or “DONE”. |
description | string | An optional description for the task. |
deviceConflictPolicy | string | Conflict resolution policy for device-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
deviceReference | object | The value of deviceReference is a link object for the BIG-IP targeted by this import request. |
link | string | URL of deviceReference |
endDateTime | string | The time the task stopped running. |
errorMessage | string | An error encountered while the task was running. There may be errors even when the task is not FAILED. |
failOnConflict | boolean | If failOnConflict is true and there are import conflicts, fail module import and do not resolve them. |
id | string | The id of the task. |
identityReferences | array | A list of user identities that initiated the task. |
link | string | URL for an user identity |
moduleList | object | List of modules being imported, with status. |
endTime | string | End time for module processing (UTC). |
errorMsg | string | Error message from module import task. |
module | string | Module object identifier. Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
properties | object | Module-specific properties. |
snapshotWorkingConfig | boolean | True if a module snapshot should be created before import. |
startTime | string | Start time for module processing (UTC). |
status | string | Final status of module-specific task. Possible values: “QUEUED”, “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
statusQual | string | If the module status is “FAILED”, this value can be “TASK_BUSY”, which indicates that the module import task was already active. |
taskReference | string | Reference to module import task. |
link | string | URL of the reference to module import task. |
name | string | An optional name for the task. |
ownerMachineId | string | In a high-availability environment, the machineId of the host running the task. |
parentTaskReference | object | The task API that initiated the task. |
link | string | URL for the task API that initiated the task. |
selfLink | string | The URL to access this item directly. |
skipClusterSync | boolean | If skipClusterSync is true, skip cluster synchronization for clustered devices. |
startDateTime | string | The time the task was started. |
status | string | Standard task status of the super-task, updated during execution. Possible values: “CREATED”, “STARTED”, “CANCEL_REQUESTED”, “CANCELED”, “FAILED” or “FINISHED”. |
taskWorkerGeneration | number | The highest generation number that task collection has received from task worker. |
userReference | string | The user that initiated the task. |
link | string | URL for userReference |
username | string | The user that initiated the task. |
versionedConflictPolicy | string | Conflict resolution policy for version-specific objects. Possible values: “NONE”, “USE_BIGIP”, “USE_BIGIQ” or “KEEP_VERSION”. |
Permissions¶
Role | Allow |
---|---|
admin | Yes |
PATCH mgmt/cm/global/tasks/device-import/<id>¶
To cancel a running super-task, or restart a super-task with a “FINISHED” or “FAILED” status, you can send a PATCH request to the endpoint and specify the super-task’s id. To cancel a running super-task, send a PATCH request to change the value of status to “CANCEL_REQUESTED”. Then send a GET request to poll the super-task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the super-task. Import tasks are retained after completion and can be restarted to re-import a module. To restart a super-task having a status of “FINISHED” or “FAILED”, send a PATCH request to change the value of status to “STARTED” and optionally change moduleList.
Request Parameters¶
The JSON in the body of the PATCH request can include the following parameters.
Name | Type | Required | Description |
---|---|---|---|
moduleList | array | True | When restarting a super-task in the “FINISHED” or “FAILED” state, you can optionally change the list of modules being imported by changing moduleList. |
module | string | True | Module object identifier. Possible values are “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”. |
status | string | True | Standard task status of the super-task, updated during execution. To cancel the super-task, this value can be changed to “CANCEL_REQUESTED”. To restart the super-task, this value can be “STARTED”. |
Response¶
HTTP/1.1 200 OK
The JSON in the body of the PATCH response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
DELETE /cm/global/tasks/device-import/<id>¶
To delete a super-task you can send a DELETE request to the endpoint and specify the super-task’s id. The super-task’s id and selfLink can be obtained from the response to a previous GET request or from the response to the original POST used to create the super-task.
Request Parameters¶
None
Query Parameters¶
None
Response¶
HTTP/1.1 200 OK
The JSON in the body of the DELETE response can be similar to the GET response.
Permissions¶
Role | Allow |
---|---|
admin | Yes |
Examples¶
POST to import multiple modules¶
POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-import
The following example creates a super-task to import a module object on BIG-IQ. Import copies the specified module objects from the BIG-IQ’s current-config to the BIG-IQ’s working-config. The JSON in the body of the POST can be similar to the following.
{
"name": "import_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"conflictPolicy": "USE_BIGIQ",
"versionedConflictPolicy": "KEEP_VERSION",
"deviceConflictPolicy": "USE_BIGIP",
"failOnConflict": true,
"skipClusterSync": true,
"moduleList": [{
"module": "firewall",
"snapshotWorkingConfig": true,
"properties": {}
}]
}
Response¶
The JSON in the response to the POST can look similar to the following. The value of selfLink is the URL for the super-task. The value of status can be “STARTED” initially, which means the task has been started. To poll for the updated status, you can send repeated GET requests to the super-task’s selfLink. Note that the status of the module is returned in moduleList.
{
"name": "import_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"conflictPolicy": "USE_BIGIQ",
"versionedConflictPolicy": "KEEP_VERSION",
"deviceConflictPolicy": "USE_BIGIP",
"failOnConflict": true,
"skipClusterSync": true,
"currentStep": "INIT",
"moduleList": [
{
"module": "firewall",
"snapshotWorkingConfig": true,
"properties": {},
"status": "STARTED",
"errorMsg": "Conflicts found, import halted.",
"startTime": "2019-08-26T19:04:13.722Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/adc-core/tasks/declare-mgmt-authority/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
}
}
],
"allModuleStatus": [
{}
],
"generation": 42,
"lastUpdateMicros": 1566831692788009,
"kind": "cm:global:tasks:device-import:importsupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-import/04d5223c-78d2-45a3-aa4b-c86da7856c68",
"id": "04d5223c-78d2-45a3-aa4b-c86da7856c68",
"status": "STARTED",
"startDateTime": "2019-08-28T14:38:25.097-0400",
"errorMessage": "Failed to process module tasks for device wurdah-itah.billerica.ma (10.255.85.115); reason: At least one module has failed",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [
{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}
],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
}
}
GET to check the task’s status¶
The following example gets the updated status for the super-task identified by id and selfLink. You can send repeated GET requests to check the status of the super-task, which can eventually update to “DONE” and “FINISHED”.
GET https://<BIG-IQ>/mgmt/cm/global/tasks/device-import/<id>
Response¶
The JSON in the response to the GET when the task is done can look similar to the following. Note that the status of the module-specific task is included in moduleList.
{
"name": "import_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"conflictPolicy": "USE_BIGIQ",
"versionedConflictPolicy": "KEEP_VERSION",
"deviceConflictPolicy": "USE_BIGIP",
"failOnConflict": true,
"skipClusterSync": true,
"currentStep": "INIT",
"moduleList": [{
"module": "firewall",
"snapshotWorkingConfig": true,
"properties": {},
"status": "FINISHED",
"errorMsg": "Conflicts found, import halted.",
"startTime": "2019-08-26T19:04:13.722Z",
"endTime": "2019-08-26T19:04:16.769Z",
"taskReference": {
"link": "https://localhost/mgmt/cm/adc-core/tasks/declare-mgmt-authority/f5b4bb89-f6c6-400a-a24d-c6ee6db5138f"
}
}],
"allModuleStatus": [{}],
"generation": 42,
"lastUpdateMicros": 1566831692788009,
"kind": "cm:global:tasks:device-import:importsupertaskitemstate",
"selfLink": "https://localhost/mgmt/cm/global/tasks/device-import/04d5223c-78d2-45a3-aa4b-c86da7856c68",
"id": "04d5223c-78d2-45a3-aa4b-c86da7856c68",
"status": "FINISHED",
"startDateTime": "2019-08-28T14:38:25.097-0400",
"endDateTime": "2019-08-28T14:38:44.608-0400",
"errorMessage": "Failed to process module tasks for device wurdah-itah.billerica.ma (10.255.85.115); reason: At least one module has failed",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}],
"ownerMachineId": "24275453-2670-4acd-ac33-875aabcfc4bf",
"taskWorkerGeneration": 42,
"username": "admin",
"parentTaskReference": {
"link": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/7e853383-4e8a-4e4b-93d8-7f117195223c"
}
}
PATCH to cancel a running super-task¶
You can send a PATCH request to cancel a running super-task specified by the task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-import/<id>
In the body of the PATCH request specify the value of status as “CANCEL_REQUESTED”.
{
"status": "CANCEL_REQUESTED"
}
Response¶
You can then send repeated GET requests to poll the super-task until the value of status updates to “CANCELLED”, “FINISHED”, or “FAILED”. The values “FINISHED” or “FAILED” indicate the request was sent too late to cancel the super-task.
PATCH to re-import a module¶
You can send a PATCH request to restart a super-task having a status of “FINISHED” or “FAILED”. Super-import tasks are retained after completion, and may be restarted to re-import a module. Specify the super-task to restart by the super-task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-import/<id>
In the body of the PATCH request specify the value of status as “STARTED”, and you can optionally change the value of moduleList.
{
"moduleList": [{
"module": "firewall"
}],
"status": "STARTED"
}
Response¶
You can then send repeated GET requests to poll the super-task until the value of status updates to “FINISHED” or “FAILED”.
PATCH to modify an module import¶
You can send a PATCH request to modify a super-task. Specify the super-task to restart by the super-task’s id.
PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-import/<id>
In the body of the PATCH request specify the values of fields that are being patch. For example, the JSON in the body of the PATCH request can look similar to the following.
{
"name": "import_10.255.85.114",
"description": null,
"deviceReference": {
"link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
},
"conflictPolicy": "USE_BIGIQ",
"versionedConflictPolicy": "KEEP_VERSION",
"deviceConflictPolicy": "USE_BIGIP",
"failOnConflict": true,
"skipClusterSync": true,
"moduleList": [{
"module": "firewall",
"snapshotWorkingConfig": true,
"properties": {}
}]
}
DELETE to delete an import task¶
The following example deletes the super-task identified by id.
DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-import/<id>
Response¶
The JSON in the response from a DELETE request is similar to a response from a GET request.