CPC Single Step Install
The CPC Single Step Install operation asynchronously performs a backup of a single CPC's firmware and then retrieves, installs, and activates a new bundle of firmware.
HTTP method and URI
POST /api/cpcs/{cpc-id}/operations/single-step-install
In this request, the URI variable {cpc-id} is the object ID of the target CPC object.
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 the bundle to be installed |
accept-firmware | Boolean | Optional | Accept the previous bundle level before installing the new level. Default value: true |
ftp-retrieve | Boolean | Optional | Retrieve internal code changes from an FTP server. Default value: false [Added by feature cpc-delete-retrieved-internal-code] |
ftp-server-host | String | Optional | The hostname for the FTP server. Note: This field is required if
ftp-retrieve is true.
[Added by feature cpc-delete-retrieved-internal-code] |
ftp-server-user | String | Optional | The username for FTP server login. Note: This field is required if
ftp-retrieve is true.
[Added by feature cpc-delete-retrieved-internal-code] |
ftp-server-password | String | Optional | The password for FTP server login. Note: This field is required if
ftp-retrieve is true.
[Added by feature cpc-delete-retrieved-internal-code] |
ftp-server-directory | String | Optional | The directory to access on the FTP server. Note: This field is required if
ftp-retrieve is true.
[Added by feature cpc-delete-retrieved-internal-code] |
ftp-server-protocol | String Enum | Optional | The protocol used to connect to the FTP server. Valid values:
Note: This field is required if ftp-retrieve is true.
[Added by feature cpc-delete-retrieved-internal-code] |
Response body contents
Once the operation is accepted, the response body contains a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
job-uri | String/ URI | URI that may be queried to retrieve status updates or used to request cancellation of the operation. |
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 the 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:
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 Single Step Install operation installs a firmware bundle on a CPC. The ec-mcl-description property of the target CPC object provides information about the firmware levels that are known to the CPC.
Note that it is not possible to remove firmware updates with this operation. Specifying a bundle-level 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.
Note that it is not possible to view MCL alerts with this operation. Specifying a bundle-level that targets firmware updates that trigger an alert during install and activate will result in an error rather than a display of the alert. If the user wishes to proceed with the operation, they will have to log on to the HMC that manages the target CPC via the local graphical user interface (GUI) or a remote web browser, then navigate to the Single Step Internal Code Changes task and rerun the operation.
The internal code that is installed during this operation can be retrieved from either the remote support system or a specified FTP server. In either case, an attempt will be made to retrieve all available internal code changes. If the bundle-level field is specified, then all retrieved internal code changes up to the specified bundle boundary will be installed on the target CPC. If the bundle-level field is omitted, then all retrieved internal code changes will be installed.
If the ftp-retrieve field is specified as false, then all possible internal code changes will be retrieved from the remote support system. If the bundle-level field is omitted, then all retrieved internal code changes will be installed on the target CPC. Otherwise, the retrieved internal code changes will be installed up to the specified bundle boundary.
If the ftp-retrieve field is specified as true, then all possible internal code changes will be retrieved from an FTP server. In order to achieve this, the ftp-server-host, ftp-server-user, ftp-server-password, ftp-server-directory, and ftp-server-protocol fields must all be included in the initial request. If the retrieval was successful, then the set of internal code changes that will be installed depends on the bundle-level field. If the bundle-level field is omitted, then all retrieved internal code changes will be installed on the target CPC. Otherwise, the retrieved internal code changes will be installed up to the specified bundle boundary. If an error occurs trying to locate the server with the specified hostname, or if authentication to the server cannot be established with provided user credentials, or if the internal code changes cannot be retrieved from their specified location, then a 409 (Conflict) will be returned.
If the API user does not have action/task permission to the Single Step Internal Code Changes 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.
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 request body field. Once started, the asynchronous job performs additional validation of the request body fields. If the bundle-level does not exist or is known but not yet retrieved or is already installed on the target CPC, or if the targeted set of firmware contains disruptive updates, 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.
- A backup of the target CPC is performed to its Support Element hard drive.
- If the value of the accept-firmware is true, the firmware currently installed on the target CPC is accepted. Note that once firmware is accepted, it cannot be removed.
- The uninstalled firmware identified by the bundle-level field is installed.
- The newly installed firmware is activated, which includes rebooting the CPC's Support Element.
If an error occurred when installing updates, any updates that were successfully installed are rolled back. If a failure occurs after the firmware is accepted, the firmware remains accepted.
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.
This operation supports cancellation of its asynchronous processing identified by the Job URI provided in the response body. Use the Cancel Job operation to request cancellation. Note there are only a few interruption points in the firmware install process, so it may be some time before the job is canceled, and after some point, will continue to completion. The job status and reason codes will indicate whether the job was canceled or ran to completion. If the job is successfully canceled, any steps that were successfully completed will not be rolled back.
Authorization requirements
- Object-access permission to the CPC object whose object ID is {cpc-id}
- Action/task permission for the Single Step Internal Code Changes 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. |
403 (Forbidden) | 1 | The API user does not have action/task permission to the Single Step Internal Code Changes 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 to the object. |
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
Job status code | Job 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 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 targeted set of firmware updates contains one or more updates that are disruptive to CPC operations. | |
401 | 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, and then navigate to the Single Step Internal Code Change task and rerun the operation. | |
409 (Conflict) | 341 | The CPC identified by {cpc-id} does not have an active connection to the Support System. |
342 | Connection to the FTP server specified in the ftp-server-host field failed. Verify that the hostname is well-defined and exists. | |
343 | Authentication to the FTP server failed with the provided values for the ftp-server-user and ftp-server-password fields. | |
344 | No host key can be found while attempting to access the FTP server specified in the ftp-server-host field via the SFTP protocol. Navigate to the Manage SSH Keys task in order to add a key for the host. | |
345 | Connection to the FTP server specified in the ftp-server-host field using the FTPS protocol could not be established due to the host's certificate not being recognized. Navigate to the Certificate Management task to import the certificate. | |
347 | Failure occurred while attempting to retrieve the internal code changes contained in the ftp-server-directory field on the FTP server. | |
367 | Change Management is not enabled on the CPE identified by {cpc-id}. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.