CPC Install and Activate
The CPC Install and Activate operation installs and activates firmware on a specific CPC. [Added by feature cpc-install-and-activate]
HTTP method and URI
POST /api/cpcs/{cpc-id}/operations/install-and-activate
In this request, the URI variable {cpc-id} is the Object ID of the target CPC.
Request body contents
The request body is expected to contain a JSON object with the following fields:
Name | Type | Req/Opt | Description |
---|---|---|---|
bundle-level | String | Optional | Name of bundle to be installed. The bundle-level field cannot be present in the request body if the ec-levels field is present. |
ec-levels | Array of ec-level objects | Optional | Array of nested ec-level objects (defined in the next table) that
indicate the engineering change levels to be installed. The ec-levels field cannot be present in the request body if the bundle-level field is present. |
install-disruptive | Boolean | Optional | Indicates if disruptive changes should be installed. If true, all
firmware will be installed regardless of whether it is disruptive to CPC operations. If false
and bundle-level or ec-levels is specified, the request will fail if the operation
encounters a disruptive change. If false, and neither bundle-level or ec-levels
are specified, all concurrent changes will be installed, and the disruptive ones will be left
uninstalled. The install-disruptive field may not be present in the request body if the bundle-level field is present. Default value: false |
An ec-level object contains information about a single Microcode Level (MCL) associated with an Engineering Change (EC) stream. Each ec-level object contains the following fields:
Name | Type | Req/Opt | Description |
---|---|---|---|
number | String (1-6) | Required | Engineering Change (EC) number. |
mcl | String (1-3) | Optional | A three-character decimal string that identifies the target Microcode Level
(MCL) for the EC identified by number. If the value is less than three characters, it is padded on the front with zeros. The decimal value must not be specified as all zeros. Doing so will result in an exception since a value of “000” is considered the current base code level for an EC stream. If the mcl field is omitted, all MCLs currently available for the EC stream will be included. |
Response body contents
Once the install and activate 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 Job status and reason codes. 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, or a description of firmware updates that are still pending when the operation was partially successful. |
Description
The CPC Install and Activate operation installs and activates firmware updates on a CPC. 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. MCLs from multiple ECs are packaged together and assigned a Bundle Level. If the bundle-level field is present in the request body, all MCLs contained in the target bundle that have not already been installed on the target CPC are installed. If the ec-levels field is present in the request body, it identifies a set of EC MCLs that are to be installed on the target CPC. If neither the bundle-level or ec-levels fields are present, all firmware that has been retrieved, but not yet installed, is installed on the target CPC. Both the bundle-level and ec-levels cannot be present in the request body.
Note that it is not possible to remove firmware updates with this operation. Specifying a bundle-level or ec-levels field value that targets firmware updates that are already installed will result in an error rather than a removal of the firmware down to the specified level. Firmware can only be removed on a CPC by navigating to the Remove and activate changes operation in the Change Internal Code task.
The vast majority of firmware updates can be installed without disrupting CPC operations. Rarely, a firmware update will be released that does. To avoid inadvertently affecting CPC operations, the API client must explicitly give permission to install disruptive updates by specifying the install-disruptive field with a value of true. If a value of false is specified, or if the install-disruptive field is not present in the request body, and the targeted firmware contains a disruptive change, the behavior differs based on whether specific change levels have been specified. If the bundle-level or ec-levels field is present in the request body, the asynchronous job will fail immediately. If neither the bundle-level or ec-levels fields are present, all of the concurrent firmware updates will be installed and the disruptive ones will be left uninstalled. Disruptive updates cannot be installed by bundle, so the install-disruptive field my not be present in the request body if the bundle-level field is present.
If the API user does not have action/task permission to the Change Internal Code task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if {cpc-id} does not identify a CPC object on the Console to which the API user has object-access permission. A 409 (Conflict) status code is returned if the target CPC is busy on the Console. A 503 (Service Unavailable) status code is returned if the Console is not communicating with the CPC.
If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because the bundle-level field is present in the request body and either the ec-levels or install-disruptive fields are also present.
If the request body contents are valid, a 202 (Accepted) response is returned and an asynchronous job is started to install the firmware updates identified by the bundle-level or ec-levels request body fields. Once started, the asynchronous job performs additional validation of the request body fields. If the bundle-level field is present in the request body but the identified bundle does not exist or is known but not yet retrieved or is already installed on the target CPC, or 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 or is already installed on the target CPC, 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 target CPC, or if the ec-levels field identifies microcode levels that have dependencies on microcode levels that are not specified.
If the request body contents are valid, the firmware updates identified by the bundle-level or ec-levels request body fields are installed. If all updates are installed successfully, they are activated, which includes a restart of the target CPC's Support Element. If an error occurred when installing updates, any updates that were successfully installed are rolled back.
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). It is possible that additional actions, such as configuring virtual adapters off and on, may be required to fully activate certain firmware updates. If this is the case, the asynchronous job completion status will be 200 (OK), indicating overall success of the operation, but the result will contain a job-results field with a message indicating some firmware updates remain in a pending state. The View Internal Code Changes Summary task on the Console or Support Element user interface will provide a list of the additional actions that are required. It is not possible to query this information via the API. It is also possible to get a 200 (OK) status if the targeted firmware contains a change that is disruptive to CPC operations. In this case, all of the MCLs that could be concurrently installed were installed, and the disruptive MCLs were left uninstalled. The job-results field message will indicate which MCLs were left uninstalled.
Authorization requirements
This operation has the following authorization requirements:
- Object-access permission to the CPC whose object-id is {cpc-id}.
- Action/task permission for the Change 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 Response body contents.
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. |
15 | The bundle-level and ec-levels fields are both present in the request body. | |
15 | The bundle-level and install-disruptive fields are both present in the request body | |
403 (Forbidden) | 1 | The API user does not have action/task permission to the Change Internal Code task. |
404 (Not Found) | 1 | A CPC with the object-id {cpc-id} does not exist on the Console or the API user does not have object-access permission for it. |
409 (Conflict) | 2 | The CPC object with the object-id {cpc-id}was busy and the request timed out. |
503 (Service Unavailable) | 1 | The request could not be processed because the Console is not currently communicating with the SE needed to perform the requested operation. |
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 |
---|---|---|
200 (OK | N/A | The operation completed successfully, but some firmware remains in a pending state. |
204 (No Content) | N/A | The operation completed successfully. |
400 (Bad Request | 354 | The bundle identified by bundle-level does not exist on the target CPC. |
355 | The bundle identified by bundle-level is known on the target CPC, but has not yet been retrieved. | |
356 | The bundle identified by bundle-level is already installed on the target CPC. | |
357 | There are installed MCLs currently installed on the target CPC that are beyond the bundle identified by bundle-level. | |
358 | The bundle identified by bundle-level has been marked as invalid for install. | |
359 | The bundle identified by bundle-level contains one or more updates that are disruptive to CPC operations and the install-disruptive field was omitted or specified with a value of false. | |
366 | There are MCL alerts present for install and activate of the bundle identified by bundle-level. Log on to the GUI of the Console managing the target CPC, then navigate to the Change Internal Code task and rerun the operation. | |
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 invalid. | |
380 | The ec-levels field contains an ec-level object with a number and mcl combination that is disruptive to CPC operations. This cannot occur since the install-disruptive field was omitted or specified with a value of false. | |
409 (Conflict) | 341 | The CPC identified by {cpc-id} does not have an active connection to the Support System. |
367 | Change Management is not enabled on the CPC identified by {cpc-id}. | |
383 | There are no internal code changes on the system, 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.