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.

Previous Next