Import DPM Configuration
The Import DPM Configuration operation imports DPM objects such as partitions, NICs, HBAs, virtual functions, and their properties. It also restores DPM-specific CPC properties, like the description, auto-start partition list and capacity groups.
HTTP method and URI
POST /api/cpcs/{cpc-id}/operations/import-dpm-config
In this request, the URI variable {cpc-id} is the object ID of the CPC.
Request body contents
The request body is expected to contain a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
cpc-properties | cpc-info object | Optional |
An object containing the names of CPC properties and the values to which each of those properties is to be set. This is a very limited set of CPC properties relevant to CPCs enabled for DPM mode. |
se-version | String (1-8) | Required | The internal code release level of the primary SE on the machine from which the configuration was exported. |
available-features-list | Array of cpc-feature-info objects | Required | The list of optional features or behaviors supported by the CPC on the machine from which the configuration was exported. If the CPC has no optional features, then the array must be empty. |
available-api-features-list | Array of String | Optional | The API features available on the source system, as returned by the List CPC API Features operation, issued when the configuration information was exported. |
preserve-uris | Boolean | Optional | Controls whether object IDs / element IDs are preserved or if new object IDs /
element IDs will be generated. Because those IDs are components of URIs, this field controls whether
the URIs of imported objects are preserved. This applies to all objects that
will be recreated, for example Partitions, HBAs, NICs, Virtual Functions, Capacity Groups,
etc. Note: This does not apply to existing objects, such as
Adapters.
Default: false |
preserve-wwpns | Boolean | Optional | Controls whether HBA WWPNs are preserved or if new WWPNs will be generated.
Default: false |
adapter-mapping | Array of adapter-mapping-info objects | Optional | Array of adapter mapping information objects. Required when the I/O adapter configuration on this machine differs from that of the machine from which the configuration was exported. |
partitions | Array of objects | Required | Array of objects containing the properties of the Partitions to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Partition Properties operation issued when the configuration information was exported. |
nics | Array of objects | Optional | Array of objects containing the properties of the NICs to be imported. Each element of this array is expected to be the equivalent of a response body from a Get NIC Properties operation issued when the configuration information was exported. |
hbas | Array of objects | Optional | Array of objects containing the properties of the HBAs to be imported. Each element of this array is expected to be the equivalent of a response body from a Get HBA Properties operation issued when the configuration information was exported. |
virtual-functions | Array of objects | Optional | Array of objects containing the properties of the Virtual Functions to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Function Properties operation issued when the configuration information was exported. |
adapters | Array of objects | Required | Array of objects containing the properties of the Adapters in the exported configuration. Each element of this array is expected to be the equivalent of a response body from a Get Adapter Properties operation issued when the configuration information was exported. This will not recreate any Adapters; it is used for internal purposes only. |
virtual-switches | Array of objects | Optional | Array of objects containing the properties of the Virtual Switches in the exported configuration. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Switch Properties operation issued when the configuration information was exported. This will not recreate any Virtual Switches; it is used for internal purposes only. |
capacity-groups | Array of objects | Optional | Array of objects containing the properties of the Capacity Groups to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Capacity Group Properties operation issued when the configuration information was exported. |
storage-sites | Array of objects | Optional | Array of objects containing the properties of the Storage Sites to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Site Properties operation issued when the configuration information was exported. |
storage-subsystems | Array of objects | Optional | Array of objects containing the properties of the Storage Subsystems to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Subsystem Properties operation issued when the configuration information was exported. |
storage-fabrics | Array of objects | Optional | Array of objects containing the properties of the Storage Fabrics to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Fabric Properties operation issued when the configuration information was exported. |
storage-switches | Array of objects | Optional | Array of objects containing the properties of the Storage Switches to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Switch Properties operation issued when the configuration information was exported. |
storage-control-units | Array of objects | Optional | Array of objects containing the properties of the Storage Control Units to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Control Unit Properties operation issued when the configuration information was exported. |
storage-paths | Array of objects | Optional | Array of objects containing the properties of the Storage Paths to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Path Properties operation issued when the configuration information was exported. |
storage-groups | Array of objects | Optional | Array of objects containing the properties of the Storage Groups to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Group Properties operation issued when the configuration information was exported. |
storage-volumes | Array of objects | Optional | Array of objects containing the properties of the Storage Volumes to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Volume Properties operation issued when the configuration information was exported. |
storage-templates | Array of objects | Optional | Array of objects containing the properties of the Storage Templates to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Template Properties operation issued when the configuration information was exported. |
storage-template-volumes | Array of objects | Optional | Array of objects containing the properties of the Storage Template Volumes to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Template Volume Properties operation issued when the configuration information was exported. |
virtual-storage-resources | Array of objects | Optional | Array of objects containing the properties of the Virtual Storage Resources to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Storage Resources Properties operation issued when the configuration information was exported. |
storage-ports | Array of objects | Optional | Array of objects containing the properties of the Storage Ports to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Port Properties operation issued when the configuration information was exported. |
network-ports | Array of objects | Optional | Array of objects containing the properties of the Network Ports to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Network Port Properties operation issued when the configuration information was exported. |
partition-links | Array of objects | Optional |
Array of objects containing the properties of the Partition Links to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Partition Link Properties operation issued when the configuration information was exported. |
certificates | Array of objects | Optional | Array of objects containing the properties of the Certificate objects to be
imported and possibly assigned to one or more Partitions. Each element of this array is expected to
be the equivalent of a response body from a Get Certificate Properties operation
enriched with the fields of the corresponding response body from a Get Encoded
Certificate operation, both issued when the configuration information was exported. [Added by feature secure-boot-with-certificates] |
The cpc-info nested object contains the following fields:
Name | Type | Description |
---|---|---|
description | String (1-1024) | The descriptive text associated with this CPC object |
auto-start-list | Array of auto-start-entry objects | An array of auto-start-entry objects in sequence, each representing a single partition or a group of partitions that are automatically started when this CPC is started. The format of that object is described in the Class specific additional properties. |
The adapter-mapping-info nested object contains the following fields:
Name | Type | Description |
---|---|---|
new-adapter-id | String (3) | The hexadecimal value of the adapter ID (PCHID) on this machine |
old-adapter-id | String (3) | The hexadecimal value of the adapter ID (PCHID) on the old machine |
Response body contents
On successful completion, the response body contains a JSON object with the following field:
Name | Type | Description |
---|---|---|
output | Array of output-details objects | An array of output-details objects containing detailed information about the parts of the configuration that were not restored. |
Each nested output-details info object contains the following fields:
Name | Type | Description |
---|---|---|
category | String/ Enum | One of the following, describing the category of the message:
|
items | Array of String | Additional details about which resources were modified or not restored. The value of the category field defines the contents of this field. |
Description
This operation restores a full DPM configuration with all its artifacts like partitions, HBAs, NICs, Accelerators, and Crypto devices. Unique identifiers like Object IDs and WWPNs are preserved. This task is mainly intended for migrating a DPM configuration from an older machine to a new machine. When migrating configurations between machines of the same generation, you have to ensure consistent feature enablement settings. Migrating from a newer machine generation to an older one is not supported. The operation stops on the first fatal error. Non-fatal errors do not stop the import and provide information about unrestored objects within the response body. The request body may contain the same set of properties as generated by the Get Inventory operation.Authorization requirements
- Object-access permission to the CPC object designated by {cpc-id}
- Action/task permission to the Import Dynamic Partition Manager Configuration task.
- Object-access permission to Secure Boot Certificate objects (only applies when the request body contains one or more secure boot Certificate objects to be assigned to Partitions). [Added by feature secure-boot-with-certificates]
- Action/task permission for the Import Secure Boot Certificates task (only applies when the request body contains one or more Certificate objects). [Added by feature secure-boot-with-certificates]
- Action/task permission for the Assign Secure Boot Certificates task (only applies when the request body contains one or more secure boot Certificate objects to be assigned to Partitions). [Added by feature secure-boot-with-certificates]
HTTP status and reason codes
On success, HTTP status code 204 (No Content) is returned and no response body is provided. If not all parts of the configuration could be restored, a 200 (OK) is returned and the response body provides additional details.
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.
In contrast to other operations, the following table for HTTP status and reason codes only covers key basic error conditions, as it is not feasible to track all potential error cases when importing a potentially large DPM configuration into a new system (that might already contain DPM configuration objects). In general, any error response that corresponding operations to create/attach configuration elements might emit are possible here.
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. |
7 | The Firmware Feature enablement of the designated CPC does not support the provided configuration objects. The API features availability on the designated CPC or Console does not support the provided configuration objects. | |
100 | The provided se-version is not supported for the import operation of this CPC | |
403 (Forbidden) | 1 | The API user does not have the required permission for this operation. |
404 (Not Found) | 1 | The object ID in the URI {cpc-id} does not designate an existing CPC object, or the API user does not have object-access permission to it. |
4 | The SE associated with the CPC designated by the request URI is not on the required code level to support this operation. | |
409 (Conflict) | 1 | The state of the CPC is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions" |
5 | The operation cannot be performed because the CPC designated by the URI is not in DPM mode. | |
8 | An object with the same URI as one in the request body already exists. | |
503 (Service Unavailable) | 1 | The request could not be processed because the HMC is not 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.
Example HTTP interaction
Usage notes
- There is an open source command line tool called zhmc, available from https://github.com/zhmcclient/zhmccli. This tool can assist
with:
- Creating the input data required for this operation by exporting the configuration of an existing machine
- Invoking this operation using that previously generated data on a new machine
Note: When using the tool, ensure to always use the latest version, and to study the corresponding release information and change history. - By default, only the SERVICE user ID on the HMC has the required task permission for this operation, and that user ID is not enabled for Web Services APIs by default.
- By default, object IDs and element IDs are not preserved; instead, new unique IDs are generated when importing the objects. This prevents the possibility of duplicate IDs, which would occur when both the new and old systems are attached to the same HMC after the configuration is imported with this operation. The preserve-uris field can be specified as true to preserve the IDs, which can be helpful for situations that depend on the IDs, such as a network (PXE) boot. But care must be taken to never attach both systems to the same HMC if that option is used during this operation. Doing so may result in unpredictable behavior due to the presence of duplicate IDs.
- By default, the WWPNs of the HBAs are not preserved; instead, new WWPNs are generated when importing the HBAs. The generated WWPNs will match the I/O serial number of the new machine. If the new machine will have the same I/O serial number as the old machine, then it is appropriate to specify preserve-wwpns as true so that the HBAs are imported with their original WWPNs.
- The operation restores property settings in certain adapters (for example: the type property for storage adapters). However, it does not restore the crypto-type property for crypto adapters; you need to ensure that the target crypto adapters in the new system are set up to match that type. It is recommended that you manually inspect the crypto-type property for all crypto adapters prior to import, and make any changes that might be needed, using the Manage Adapters task.