Device RMA

Overview

Use this BIG-IQ API to create a super-task which can remove multiple modules from a specified BIG-IP. To remove multiple modules, send a POST request to the device-remove-mgmt-authority task collection on the BIG-IQ with moduleList a list of only the modules (firewall, security_shared, asm, adc_core, access, dns, fps or sslo) being removed. The API response can contain information about the status of the super-task and the status of each individual module because the system runs a separate module removal task for each module specified in moduleList.

REST Endpoint: mgmt/cm/global/tasks/device-remove-mgmt-authority

Requests

To create a super-task which removes multiple modules from a BIG-IP, send a POST request to the device-remove-mgmt-authority endpoint.

POST mgmt/cm/global/tasks/device-remove-mgmt-authority

Request Parameters

The JSON in the body of the POST request can include the following parameters. Include a moduleList of only the modules (firewall, security_shared, asm, adc_core, access, dns, fps or sslo) being removed.

Name Type Required Description
name string False An optional name for the super-task.
description string False An optional description for the super-task.
deviceReference object True The value of deviceReference is a link object for the BIG-IP targeted by this removal request.
     link string True URL of deviceReference
moduleList array True List of module objects for modules to be removed. In the POST request, only the value in the module field needs to be provided. This task can remove modules whether or not they have been discovered.
     module string True Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”.

Query Parameters

None

Response

The JSON in the body of the response to the POST request 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 because a separate module removal task is run for each module in moduleList.

HTTP/1.1 200 OK

Name Type Description
ItemState object State of the removal task.
     currentStep string Current step of the removal task. Possible values: “INIT”, “CHECK_REMOVED_MODULES”, “GET_DEVICE_IN_GROUPS”, “GET_DEVICE_IN-BIGIP_GROUP”, “CHECK_RUNNING_TASKS”, “CHECK_APPLICATIONS”, “CHECK_SCALING_GROUPS”, “PROCESS_MODULE_TASKS”, “DELETE_MODULE_TASKS”, “FAILED” or “DONE”.
     description string An optional description for the task.
     deviceReference string The value of deviceReference is a link object for the BIG-IP targeted by this removal 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 can be errors even when the task’s status is not “FAILED”.
     id string The id of the task.
     moduleList object List of modules being removed, with status.
          endTime string End time for module processing (UTC).
          errorMsg string Error message from module removal task.
          module string Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”.
          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 removal task was already active.
          taskReference string Reference to module removal task.
          link string URL of the reference to module removal task.
     name string An optional name for the task.
     selfLink string The URL to access this item directly.
     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”.
     userReference string The user that initiated the task.
          link string URL for userReference
     identityReferences array A list of user identities that initiated the task.
          link string URL for an user identity
     ownerMachineId string In a high-availability environment, the machineId of the host running the task.
     taskWorkerGeneration number The highest generation number that task collection has received from task worker.
     parentTaskReference object The task API that initiated the task.
          link string URL for the task API that initiated the task.
     username string The user that initiated the task.

Permissions

Role Allow
admin Yes

GET /cm/global/tasks/device-remove-mgmt-authority/<id>

To check the status of a super-task you can send a GET request to the device-remove-mgmt-authority endpoint and specify the super-task’s id. The status of the individual module removal tasks are returned in moduleList. 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

Name Type Description
ItemState object State of the removal task
     currentStep string Current step of the removal task. Possible values: “INIT”, “CHECK_REMOVED_MODULES”, “GET_DEVICE_IN_GROUPS”, “GET_DEVICE_IN-BIGIP_GROUP”, “CHECK_RUNNING_TASKS”, “CHECK_APPLICATIONS”, “CHECK_SCALING_GROUPS”, “PROCESS_MODULE_TASKS”, “DELETE_MODULE_TASKS”, “FAILED” or “DONE”.
     description string An optional description for the task.
     deviceReference string The device for modules being removed, as a machine id resolver device reference.
          link string URL of deviceReference
     endDateTime string The time the task stopped running.
     errorMessage string An error encountered while the task was running. There can be errors even when the task’s status is not “FAILED”.
     id string The id for the task.
     moduleList object List of module names of modules being removed, with status.
          endTime string End time for module processing (UTC).
          errorMsg string Error message from module removal task.
          module string Possible values: “firewall”, “security_shared”, “asm”, “adc_core”, “access”, “dns”, “fps” or “sslo”.
          startTime string Start time for module processing (UTC).
          status string Final status of module removal 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 removal task was already active.
          taskReference string Reference to module removal task.
          link string URL of the reference to module removal task.
     name string An optional name for the task.
     selfLink string The URL to access this item directly.
     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”.
     userReference string The user that initiated the task.
          link string URL for userReference
     identityReferences array A list of user identities that initiated the task.
          link string URL for an user identity
     ownerMachineId string In a high-availability environment, the machineId of the host running the task.
     taskWorkerGeneration number The highest generation number that task collection has received from task worker.
     parentTaskReference object The task API that initiated the task.
          link string URL for the task API that initiated the task.
     username string The user that initiated the task.

Permissions

Role Allow
admin Yes

PATCH mgmt/cm/global/tasks/device-remove-mgmt-authority/<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 device-remove-mgmt-authority 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 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. 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 request parameters in 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 removed by changing moduleList.
     module string True 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 response to a PATCH request will be the same as a GET to retrieve the task’s state.

Permissions

Role Allow
admin Yes

DELETE /cm/global/tasks/device-remove-mgmt-authority/<id>

To delete a super-task you can send a DELETE request to the device-remove-mgmt-authority 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 response to a DELETE request will be the same as a GET to retrieve the task’s state.

Permissions

Role Allow
admin Yes

Examples

POST to remove multiple modules

POST https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority

The following example creates a super-task to remove a module from the specified BIG-IP. The JSON in the body of the POST can be similar to the following.

{
    "name": "device-rma_10.255.85.114",
    "description": null,
    "deviceReference": {
            "link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
    },
    "moduleList": [{
            "module": "firewall"
    }]
}

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 removal is returned in moduleList.

{
    "name": "device-rma_10.255.85.114",
    "description": null,
    "deviceReference": {
            "link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
    },
    "currentStep": "DONE",
    "moduleList": [{
            "module": "firewall",
            "status": "FINISHED",
            "errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
            "startTime": "2019-08-26T19:04:13.722Z",
            "endTime": "2019-08-26T19:04:16.769Z",
            "taskReference": {
                    "link": "https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a"
            }
    }],
    "generation": 42,
    "lastUpdateMicros": 1566831709720008,
    "kind": "cm:global:tasks:device-remove-mgmt-authority:rmasupertaskitemstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-mgmt-authority/5de37aee-0845-4fb3-aa94-48e020c43225",
    "id": "5de37aee-0845-4fb3-aa94-48e020c43225",
    "status": "STARTED",
    "startDateTime": "2019-08-22T16:29:46.806-0400",
    "endDateTime": "2019-08-22T16:30:03.471-0400",
    "errorMessage": "Device in use by application 'sample'",
    "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": {}
}

GET to check the updated 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-remove-mgmt-authority/<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 removal is returned in moduleList.

{
    "name": "device-rma_10.255.85.114",
    "description": null,
    "deviceReference": {
            "link": "https://localhost/mgmt/cm/system/machineid-resolver/d1481f9a-1798-4ab8-a9c5-fa02e47a3990"
    },
    "currentStep": "DONE",
    "moduleList": [{
            "module": "firewall",
            "status": "FINISHED",
            "errorMsg": "Task https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a is still in process, wait for this task to complete.",
            "startTime": "2019-08-26T19:04:13.722Z",
            "endTime": "2019-08-26T19:04:16.769Z",
            "taskReference": {
                    "link": "https://localhost/mgmt/cm/firewall/tasks/remove-mgmt-authority/57e32353-5a91-470a-be34-a5ce1a17973a"
            }
    }],
    "generation": 42,
    "lastUpdateMicros": 1566831709720008,
    "kind": "cm:global:tasks:device-remove-mgmt-authority:rmasupertaskitemstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-remove-mgmt-authority/5de37aee-0845-4fb3-aa94-48e020c43225",
    "id": "5de37aee-0845-4fb3-aa94-48e020c43225",
    "status": "STARTED",
    "startDateTime": "2019-08-22T16:29:46.806-0400",
    "endDateTime": "2019-08-22T16:30:03.471-0400",
    "errorMessage": "Device in use by application 'sample'",
    "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": {}
}

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-remove-mgmt-authority/<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 restart a super-task

You can send a PATCH request to restart a super-task having a status of “FINISHED” or “FAILED”. Specify the super-task to restart by the super-task’s id.

PATCH https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<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”.

DELETE to delete a removal task

The following example deletes the super-task identified by id.

DELETE https://<BIG-IQ>/mgmt/cm/global/tasks/device-remove-mgmt-authority/<id>

Response

The JSON in the response from a DELETE request is similar to a response from a GET request.