Console Delete Retrieved Internal Code

The Console Delete Retrieved Internal Code operation deletes retrieved internal code that has not been installed on the Console. [Added by feature hmc-delete-retrieved-internal-code]

HTTP method and URI

POST /api/console/operations/delete-retrieved-internal-code

Request body contents

The request body is expected to contain a JSON object with the following fields:

Name Type Req/Opt Description
ec-levels Array of ec-level objects Optional Array of nested ec-level objects (defined in Table 1) that indicate the uninstalled engineering change levels to be deleted.

Default: All retrieved, uninstalled MCLs are deleted down to the applied levels.

Response body contents

Once the Console Delete Retrieved Internal Code request is accepted, the response body contains a JSON object with the following fields

Name Type Description
job-uri String/ URI URI that may be queried to retrieve status updates.

Asynchronous result description

Once the operation has completed, a job-completion notification is sent, and results are available for the asynchronous portion of this operation. These results are retrieved using the Query Job Status operation directed at the job URI provided in the response body.

The result document returned by the Query Job Status operation is specified in the description for the Query Job Status operation. When the status of the job is "complete", the results include a job completion status code and reason code (fields job-status-code and job-reason-code) which are set as indicated in Response body contents. The job-results field is null when this operation is successful. When it is not successful or partially successful, the job-results field contains an object with the following field:
Name Type Description
message String The message text describing the detailed error that occurred when the operation was not successful.

Description

The Console Delete Retrieved Internal Code operation deletes retrieved internal code that has not been installed on the Console. The firmware is segmented into different subsystems identified by Engineering Change (EC) numbers. Sets of firmware updates within a single EC are packaged together and assigned a Microcode Level (MCL). MCL packages are installed sequentially, so an MCL implies not only the firmware updates that were packaged with that MCL, but all of the MCLs that preceded it in the EC stream. If the ec-levels field is present in the request body, it identifies a set of retrieved, but uninstalled EC MCLs that are to be deleted on the Console. If the ec-levels field is not present, then all the firmware that is currently retrieved, but not installed, will be deleted from the Console.

If the API user does not have action/task permission to the Change Console Internal Code task, a 403 (Forbidden) status code is returned. A 409 (Conflict) status code is returned if the Console is busy. If the request body fails to validate, a 400 (Bad Request) status code is returned.

If the request body contents are valid, a 202 (Accepted) response is returned and an asynchronous job is started to remove the firmware updates identified by the ec-levels request body field. Once started, the asynchronous job performs additional validation of the request body fields. If the ec-levels field is present in the request body and references an Engineering Change (EC) number or Microcode Level (MCL) that does not exist on the Console, a 400 (Bad Request) is returned in response to a Query Job Status Request. A 409 (Conflict) is returned if Change Management is not enabled, or if a connection to the Support System is not available on the Console, or if the ec-levels field identifies microcode levels that are already installed on the system instead of only being retrieved.

If the request body contents are valid, the firmware updates identified by the ec-levels request body field are deleted. If an error occurred when deleting the updates, then only the updates that were unsuccessfully deleted will remain on the system; any updates that were deleted before reaching an error will remain deleted upon completion of the operation.

When the asynchronous job competes, the response to a Query Job Status request will include a status of "complete". If the operation was successful, the completion status will be 204 (No Content).

Authorization requirements

This operation has the following authorization requirements:

  • Action/task permission for the Change Console Internal Code task.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) is returned and the response body is provided as described in Job status and reason codes.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
403 (Forbidden) 1 The API user does not have action/task permission to the Change Console Internal Code task.
409 (Conflict) 2 The target console was busy and the request timed out.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Job status and reason codes

HTTP error status code Reason code Description
204 (No Content) N/A The operation completed successfully.
400 (Bad Request) 378 The ec-levels field contains an ec-level object with a number and mcl combination that does not identify a known component and is therefore not valid.
400 (Bad Request 367 Change Management is not enabled on the target console.
383 There are no internal code changes on the target console, so the change internal code operation could not be performed.
385 The ec-levels field contains an ec-level object with a number and mcl combination that is not properly bounded by the current applied and staged levels.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Console Delete Retrieved Internal Code: Request
POST /api/console/operations/delete-retrieved-internal-code HTTP/1.1
x-api-session: 4pse48gtmvnkgmsx9sbccibq4xsrw7e6ekpfy5hkukm4n3d8n
Content-Type: application/json
Content-Length: 51
{
   "ec-levels":[
      {
         "mcl":"001",
         "number":"P30805"
      }
   ]
}
Figure 2. Console Delete Retrieved Internal Code: Response
202 Accepted
Server: Hardware management console API web server / 2.0
Cache-control: no-cache
Date: Wed, 25 Oct 2023 14:25:01 GMT
Content-Type: application/json
Content-Length: 60
{
   "job-uri":"/api/jobs/485bbd9e-7342-11ee-bc9e-fa163e440a5c"
}