IBM

IBM Z
Hardware Management Console Web Services API
Version 2.14.0
SC27-2636-04
Level 04a
IBM

IBM Z
Hardware Management Console Web Services API
Version 2.14.0
SC27-2636-04
Level 04a

Note:
Before you use this information and the product it supports, read the information in “Safety” on
page xxix, Appendix E, “Notices,” on page 1405, and IBM Systems Environmental Notices and User
Guide, Z125–5823.

This edition, SC27-2636-04, applies to the IBM Z and IBM LinuxONE servers. This edition replaces SC27-2636-03.
There might be a newer version of this document in a PDF file available on Resource Link. Go to
http://www.ibm.com/servers/resourcelink and click Library on the navigation bar.
© Copyright IBM Corporation 2017, 2018.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Level 04a

Contents
Figures . . . . . . . . . . . . . . . xi Common request validation reason codes . . . 41
Common request processing reason codes . . . 45
Tables . . . . . . . . . . . . . . . xxi Use of chunked response encoding . . . . . . 45
Filter query parameters . . . . . . . . . . 45
Regular expression syntax . . . . . . . . 46
Safety . . . . . . . . . . . . . . xxix
Safety notices . . . . . . . . . . . . . xxix
Chapter 4. Asynchronous notification 47
World trade safety information . . . . . . xxix
JMS basics . . . . . . . . . . . . . . . 47
Laser safety information . . . . . . . . . xxix
Connecting to the API message broker . . . . . 47
Laser compliance . . . . . . . . . . . xxix
Per-session notification topics . . . . . . . . 48
Notification message formats . . . . . . . . 49
About this publication . . . . . . . xxxi Common message characteristics . . . . . . 49
Related publications . . . . . . . . . . . xxxi Status change notification. . . . . . . . . 51
Related HMC and SE console information . . . xxxi Property change notification . . . . . . . . 52
Extending zBX connectivity options to Layer-2 xxxi Inventory change notification . . . . . . . 53
Revisions . . . . . . . . . . . . . . xxxi Job completion notification . . . . . . . . 54
Accessibility . . . . . . . . . . . . . xxxii Log entry notification . . . . . . . . . . 54
Accessibility features . . . . . . . . . xxxii Operating system message notification . . . . 55
Keyboard navigation . . . . . . . . . xxxii
Consult assistive technologies . . . . . . xxxii
Chapter 5. Data model definitions . . . 57
IBM and accessibility . . . . . . . . . xxxii
Data model concepts . . . . . . . . . . . 57
How to send your comments . . . . . . . xxxii
Objects in the data model. . . . . . . . . 57
Properties in the data model. . . . . . . . 58
Part 1. Web Services API Shared data model schema elements . . . . . . 60
fundamentals . . . . . . . . . . . . 1 Base managed object properties schema . . . . 60

Chapter 1. Introduction . . . . . . . . 3 | Chapter 6. Firmware features . . . . . 63

Overview . . . . . . . . . . . . . . . 3 | Firmware feature concepts . . . . . . . . . 63
Components of the API . . . . . . . . . . 3 | dpm-storage-management . . . . . . . . 63
Enabling and accessing the API . . . . . . . . 4
Authentication and access control . . . . . . 5 Part 2. General services . . . . . . 65
Alternate HMC considerations . . . . . . . 5
Compatibility . . . . . . . . . . . . . . 6
Chapter 7. General API services . . . . 67
API versioning . . . . . . . . . . . . 6
General API services operations summary . . . . 67
Allowable changes within a major version . . . 6
Session management services . . . . . . . . 67
Requirements on client applications. . . . . . 7
Query API Version . . . . . . . . . . . 68
Summary of API version updates . . . . . . . 7
Logon . . . . . . . . . . . . . . . 70
Establish Shared Secret Key . . . . . . . . 75
Chapter 2. Base definitions . . . . . . 31 Logoff . . . . . . . . . . . . . . . 76
Data types. . . . . . . . . . . . . . . 31 Get Notification Topics . . . . . . . . . 77
Input and output representation . . . . . . . 32 Asynchronous job processing . . . . . . . . 80
Representing API data types in JSON. . . . . 32 Query Job Status . . . . . . . . . . . 80
Delete Completed Job Status. . . . . . . . 83
Chapter 3. Invoking API operations . . 35 Cancel Job . . . . . . . . . . . . . . 84
HTTP protocol standard . . . . . . . . . . 35
Connecting to the API HTTP server . . . . . . 35 Chapter 8. Inventory and metrics
HTTP header field usage . . . . . . . . . . 35 services . . . . . . . . . . . . . . 87
Required request header fields . . . . . . . 36
Inventory services operations summary . . . . . 87
Optional request headers . . . . . . . . . 36
Metrics service operations summary . . . . . . 87
Standard response headers . . . . . . . . 37
Inventory service . . . . . . . . . . . . 88
Additional response headers. . . . . . . . 38
Get Inventory . . . . . . . . . . . . 88
Media types . . . . . . . . . . . . . . 38
Metrics service . . . . . . . . . . . . . 94
HTTP status codes . . . . . . . . . . . . 39
Create Metrics Context . . . . . . . . . 94
Error response bodies . . . . . . . . . . . 40
Get Metrics . . . . . . . . . . . . . 97

© Copyright IBM Corp. 2017, 2018 iii

 Level 04a

Delete Metrics Context . . . . . . . . . 101 Update Partition Properties Asynchronously . . 186

Start Partition . . . . . . . . . . . . 190
Chapter 9. Metric groups . . . . . . 103 Stop Partition . . . . . . . . . . . . 193
Monitors dashboard metric groups . . . . . . 103 Dump Partition. . . . . . . . . . . . 195
BladeCenter temperature and power metric | Start Dump Program . . . . . . . . . . 199
group . . . . . . . . . . . . . . . 103 Perform PSW Restart . . . . . . . . . . 203
Blade power. . . . . . . . . . . . . 104 Create Virtual Function . . . . . . . . . 205
Channels . . . . . . . . . . . . . . 104 Delete Virtual Function . . . . . . . . . 208
CPC overview . . . . . . . . . . . . 104 Get Virtual Function Properties . . . . . . 209
zBX (Node) overview. . . . . . . . . . 106 Update Virtual Function Properties . . . . . 211
DPM system overview . . . . . . . . . 106 Create NIC . . . . . . . . . . . . . 213
Logical partitions . . . . . . . . . . . 107 Delete NIC . . . . . . . . . . . . . 217
Partitions . . . . . . . . . . . . . . 108 Get NIC Properties . . . . . . . . . . 218
zCPC environmentals and power . . . . . . 108 Update NIC Properties . . . . . . . . . 220
zCPC processors . . . . . . . . . . . 109 Increase Crypto Configuration. . . . . . . 223
Blade CPU and memory metric group . . . . 109 Change Crypto Domain Configuration . . . . 226
Cryptos . . . . . . . . . . . . . . 110 Decrease Crypto Configuration . . . . . . 228
Adapters . . . . . . . . . . . . . . 110 Mount ISO Image . . . . . . . . . . . 231
Flash memory adapters . . . . . . . . . 111 Unmount ISO Image . . . . . . . . . . 233
RoCE adapters . . . . . . . . . . . . 111 | Attach Storage Group to Partition . . . . . 234
Ensemble power . . . . . . . . . . . 111 | Detach Storage Group from Partition . . . . 237
Performance management metrics groups . . . . 112 Create HBA . . . . . . . . . . . . . 239
Virtual server CPU and memory metrics group 112 Delete HBA . . . . . . . . . . . . . 241
Virtualization host CPU and memory metrics Update HBA Properties . . . . . . . . . 243
group . . . . . . . . . . . . . . . 113 Get HBA Properties . . . . . . . . . . 245
Workload service class data metrics group . . . 115 Reassign Storage Adapter Port . . . . . . 247
Network management metrics . . . . . . . . 115 Send OS Command . . . . . . . . . . 249
Virtualization host and virtual server metrics 116 Open OS Message Channel . . . . . . . . 251
Optimizer network metrics . . . . . . . . 123 List OS Messages of a Partition . . . . . . 253
Network adapter port metric group . . . . . 126 Get ASCII Console WebSocket URI . . . . . 256
Network interface metric group . . . . . . 128 Inventory service data . . . . . . . . . 259
Physical switches . . . . . . . . . . . . 130 Adapter object . . . . . . . . . . . . . 262
Top-of-rack switch ports metrics . . . . . . 131 Data model . . . . . . . . . . . . . 262
ESM switch port metrics . . . . . . . . 132 List Adapters of a CPC . . . . . . . . . 273
Get Adapter Properties . . . . . . . . . 275
Update Adapter Properties . . . . . . . . 277
Part 3. CPC management . . . . . 135 Change Crypto Type . . . . . . . . . . 279
Create Hipersocket . . . . . . . . . . 282
Chapter 10. Dynamic Partition Delete Hipersocket . . . . . . . . . . 284
Manager (DPM) . . . . . . . . . . 137 Get Partitions Assigned to Adapter . . . . . 285
| FICON storage configuration . . . . . . . . 137 Get Network Port Properties . . . . . . . 287
Operations summary . . . . . . . . . . . 139 Update Network Port Properties . . . . . . 289
Partition operations summary . . . . . . . 139 Get Storage Port Properties . . . . . . . . 291
Adapter operations summary . . . . . . . 140 Update Storage Port Properties . . . . . . 292
Virtual Switch operations summary . . . . . 141 | Change Adapter Type . . . . . . . . . 294
Capacity Group operations summary . . . . 142 Inventory service data . . . . . . . . . 296
| Storage Site operations summary . . . . . . 142 Virtual Switch object . . . . . . . . . . . 298
| Storage Fabric operations summary . . . . . 142 Data model . . . . . . . . . . . . . 298
| Storage Switch operations summary . . . . . 143 List Virtual Switches of a CPC. . . . . . . 299
| Storage Subsystem operations summary . . . 143 Get Virtual Switch Properties . . . . . . . 301
| Storage Control Unit operations summary . . . 144 Get Connected VNICs of a Virtual Switch . . . 303
| Storage Group operations summary . . . . . 145 Update Virtual Switch Properties . . . . . . 304
Partition object . . . . . . . . . . . . . 146 Inventory service data . . . . . . . . . 306
Data model . . . . . . . . . . . . . 146 Capacity Group element object . . . . . . . 307
List Partitions of a CPC . . . . . . . . . 164 Data model . . . . . . . . . . . . . 307
List Permitted Partitions. . . . . . . . . 167 List Capacity Groups of a CPC . . . . . . 308
Create Partition. . . . . . . . . . . . 170 Create Capacity Group . . . . . . . . . 310
Delete Partition. . . . . . . . . . . . 175 Delete Capacity Group . . . . . . . . . 313
Delete Partition Asynchronously . . . . . . 177 Get Capacity Group Properties . . . . . . 315
Get Partition Properties . . . . . . . . . 179 Add Partition to Capacity Group . . . . . . 316
Update Partition Properties. . . . . . . . 182 Remove Partition from Capacity Group . . . 319

iv HMC Web Services API

 Level 04a

Update Capacity Group Properties . . . . . 321 | Modify Storage Group Properties. . . . . . 435
Inventory service data . . . . . . . . . 323 | Add Candidate Adapter Ports to an FCP
| Storage Site object . . . . . . . . . . . . 323 | Storage Group . . . . . . . . . . . . 443
| Data model . . . . . . . . . . . . . 323 | Remove Candidate Adapter Ports from an FCP
| List Storage Sites . . . . . . . . . . . 324 | Storage Group . . . . . . . . . . . . 446
| Create Storage Site . . . . . . . . . . 327 | List Storage Volumes of a Storage Group . . . 448
| Delete Storage Site . . . . . . . . . . 330 | Get Storage Volume Properties . . . . . . 451
| Get Storage Site Properties . . . . . . . . 331 | Fulfill FICON Storage Volume . . . . . . . 453
| Update Storage Site Properties . . . . . . 333 | Fulfill FCP Storage Volume . . . . . . . . 456
| Inventory service data . . . . . . . . . 335 | List Virtual Storage Resources of a Storage
| Storage Fabric object . . . . . . . . . . . 336 | Group . . . . . . . . . . . . . . . 459
| Data model . . . . . . . . . . . . . 336 | Get Virtual Storage Resource Properties . . . 461
| List Storage Fabrics . . . . . . . . . . 337 | Update Virtual Storage Resource Properties . . 463
| Create Storage Fabric . . . . . . . . . . 339 | Get Partitions for a Storage Group . . . . . 465
| Delete Storage Fabric . . . . . . . . . . 342 | Validate LUN Path . . . . . . . . . . 467
| Get Storage Fabric Properties . . . . . . . 343 | Inventory service data . . . . . . . . . 469
| Update Storage Fabric Properties . . . . . . 344
| Inventory service data . . . . . . . . . 346 Chapter 11. Core IBM Z resources . . 473
| Storage Switch object . . . . . . . . . . . 347 Operations Summary . . . . . . . . . . . 473
| Data model . . . . . . . . . . . . . 347 Console operations summary . . . . . . . 473
| List Storage Switches of a Storage Site . . . . 348 User operations summary . . . . . . . . 474
| List Storage Switches of a Storage Fabric . . . 351 User Role operations summary . . . . . . 475
| Define Storage Switch . . . . . . . . . 353 Task operations summary . . . . . . . . 475
| Undefine Storage Switch . . . . . . . . 355 User Pattern operations summary . . . . . 476
| Get Storage Switch Properties . . . . . . . 357 Password Rule operations summary . . . . . 476
| Update Storage Switch Properties . . . . . 358 LDAP Server Definition operations summary 476
| Move Storage Switch to Storage Site. . . . . 360 Group operations summary . . . . . . . 477
| Move Storage Switch to Storage Fabric . . . . 362 CPC operations summary . . . . . . . . 478
| Inventory service data . . . . . . . . . 364 Logical partition operation summary . . . . 479
| Storage Subsystem object . . . . . . . . . 365 Activation profile operations summary . . . . 480
| Data model . . . . . . . . . . . . . 365 Capacity record operations summary . . . . 481
| List Storage Subsystems of a Storage Site . . . 366 Shared nested objects . . . . . . . . . . . 482
| Define Storage Subsystem . . . . . . . . 369 Console object . . . . . . . . . . . . . 485
| Undefine Storage Subsystem . . . . . . . 371 Data model . . . . . . . . . . . . . 485
| Get Storage Subsystem Properties . . . . . 372 Get Console Properties . . . . . . . . . 488
| Update Storage Subsystem Properties . . . . 374 Restart Console. . . . . . . . . . . . 492
| Move Storage Subsystem to Storage Site . . . 376 Make Console Primary . . . . . . . . . 494
| Add Connection Endpoint . . . . . . . . 378 Shutdown Console . . . . . . . . . . 495
| Remove Connection Endpoint . . . . . . . 380 Reorder User Patterns . . . . . . . . . 496
| Inventory service data . . . . . . . . . 382 Get Console Audit Log . . . . . . . . . 498
| Storage Control Unit object . . . . . . . . . 383 Get Console Security Log . . . . . . . . 501
| Data model . . . . . . . . . . . . . 383 List Console Hardware Messages . . . . . . 505
| List Storage Control Units of a Storage Get Console Hardware Message Properties . . 507
| Subsystem . . . . . . . . . . . . . 386 Delete Console Hardware Message . . . . . 509
| Define Storage Control Unit . . . . . . . 388 List Unmanaged CPCs . . . . . . . . . 510
| Undefine Storage Control Unit . . . . . . 390 List Unmanaged zBX Nodes . . . . . . . 512
| Get Storage Control Unit Properties . . . . . 392 Get Mobile App Preferences . . . . . . . 514
| Update Storage Control Unit Properties . . . 394 Set Mobile App Preferences . . . . . . . 516
| Add Volume Range . . . . . . . . . . 396 Get CPC Notification Preferences for Device . . 517
| Remove Volume Range . . . . . . . . . 398 Update CPC Notification Preferences for Device 521
| Create Storage Path . . . . . . . . . . 400 Inventory service data . . . . . . . . . 525
| Delete Storage Path . . . . . . . . . . 402 User-related-access permission. . . . . . . . 529
| Get Storage Path Properties . . . . . . . 404 User object . . . . . . . . . . . . . . 530
| Update Storage Path Properties . . . . . . 405 Data model . . . . . . . . . . . . . 530
| Inventory service data . . . . . . . . . 408 List Users . . . . . . . . . . . . . 535
| Storage Group object . . . . . . . . . . . 409 Get User Properties . . . . . . . . . . 537
| Data model . . . . . . . . . . . . . 411 Update User Properties . . . . . . . . . 539
| List Storage Groups . . . . . . . . . . 424 Add User Role to User . . . . . . . . . 542
| Create Storage Group. . . . . . . . . . 426 Remove User Role from User . . . . . . . 544
| Delete Storage Group. . . . . . . . . . 430 Create User . . . . . . . . . . . . . 546
| Get Storage Group Properties . . . . . . . 433 Delete User . . . . . . . . . . . . . 549

Contents v
 Level 04a

Inventory service data . . . . . . . . . 551 Export Profiles . . . . . . . . . . . . 668

User Role object . . . . . . . . . . . . 552 Set Auto-Start List . . . . . . . . . . . 669
Data model . . . . . . . . . . . . . 553 Add Temporary Capacity . . . . . . . . 671
List User Roles . . . . . . . . . . . . 555 Remove Temporary Capacity . . . . . . . 673
Get User Role Properties . . . . . . . . 558 Swap Current Time Server . . . . . . . . 675
Update User Role Properties . . . . . . . 560 Set STP Configuration . . . . . . . . . 676
Add Permission to User Role . . . . . . . 562 Change STP-only Coordinated Timing Network 678
Remove Permission from User Role . . . . . 565 Join STP-only Coordinated Timing Network . . 680
Create User Role . . . . . . . . . . . 567 Leave STP-only Coordinated Timing Network 681
Delete User Role . . . . . . . . . . . 569 Get CPC Audit Log . . . . . . . . . . 682
Inventory service data . . . . . . . . . 571 Get CPC Security Log . . . . . . . . . 684
Task object . . . . . . . . . . . . . . 572 List CPC Hardware Messages . . . . . . . 687
Data model . . . . . . . . . . . . . 572 Get CPC Hardware Message Properties . . . 689
List Tasks. . . . . . . . . . . . . . 573 Delete CPC Hardware Message . . . . . . 691
Get Task Properties . . . . . . . . . . 574 Export WWPN List . . . . . . . . . . 693
Inventory service data . . . . . . . . . 576 | Import DPM Configuration. . . . . . . . 695
User Pattern object . . . . . . . . . . . 576 Inventory service data . . . . . . . . . 703
Data model . . . . . . . . . . . . . 577 Logical Partition object . . . . . . . . . . 703
List User Patterns . . . . . . . . . . . 578 Data model . . . . . . . . . . . . . 703
Get User Pattern Properties. . . . . . . . 580 List Logical Partitions of CPC . . . . . . . 720
Update User Pattern Properties . . . . . . 582 List Permitted Logical Partitions . . . . . . 722
Create User Pattern . . . . . . . . . . 584 Get Logical Partition Properties . . . . . . 725
Delete User Pattern . . . . . . . . . . 586 Update Logical Partition Properties . . . . . 730
Inventory service data . . . . . . . . . 588 Activate Logical Partition . . . . . . . . 731
Password Rule object . . . . . . . . . . . 588 Deactivate Logical Partition . . . . . . . 733
Data model . . . . . . . . . . . . . 589 Reset Normal . . . . . . . . . . . . 735
List Password Rules . . . . . . . . . . 591 Reset Clear . . . . . . . . . . . . . 737
Get Password Rule Properties . . . . . . . 593 Load Logical Partition . . . . . . . . . 738
Update Password Rule Properties . . . . . 595 PSW Restart . . . . . . . . . . . . . 741
Create Password Rule . . . . . . . . . 597 Start Logical Partition . . . . . . . . . 742
Delete Password Rule . . . . . . . . . 599 Stop Logical Partition . . . . . . . . . 744
Inventory service data . . . . . . . . . 600 Send OS Command . . . . . . . . . . 746
LDAP Server Definition object. . . . . . . . 602 Open OS Message Channel . . . . . . . . 747
Data model . . . . . . . . . . . . . 603 List OS Messages of a Logical Partition. . . . 749
List LDAP Server Definitions . . . . . . . 605 SCSI Load . . . . . . . . . . . . . 752
Get LDAP Server Definition Properties . . . . 607 SCSI Dump . . . . . . . . . . . . . 755
Update LDAP Server Definition Properties . . 609 List Managed Virtual Machines of a Logical
Create LDAP Server Definition . . . . . . 611 Partition . . . . . . . . . . . . . . 757
Delete LDAP Server Definition . . . . . . 613 Inventory service data . . . . . . . . . 760
Inventory service data . . . . . . . . . 614 Reset activation profile . . . . . . . . . . 760
Group Object . . . . . . . . . . . . . 615 Data model . . . . . . . . . . . . . 760
Data model . . . . . . . . . . . . . 616 List Reset Activation Profiles . . . . . . . 761
List Custom Groups . . . . . . . . . . 617 Get Reset Activation Profile Properties . . . . 763
Get Custom Group Properties . . . . . . . 619 Update Reset Activation Profile Properties. . . 765
Create Custom Group . . . . . . . . . 620 Inventory service data . . . . . . . . . 767
Delete Custom Group . . . . . . . . . 622 Image activation profile . . . . . . . . . . 767
Add Member to Custom Group . . . . . . 623 Data model . . . . . . . . . . . . . 767
Remove Member from Custom Group . . . . 625 List Image Activation Profiles . . . . . . . 786
List Custom Group Members . . . . . . . 627 Get Image Activation Profile Properties. . . . 788
Inventory service data . . . . . . . . . 628 Update Image Activation Profile Properties . . 792
CPC object . . . . . . . . . . . . . . 629 Inventory service data . . . . . . . . . 794
Data model . . . . . . . . . . . . . 629 Load activation profile . . . . . . . . . . 794
List CPC Objects . . . . . . . . . . . 644 Data model . . . . . . . . . . . . . 795
List Ensemble CPC Objects . . . . . . . . 646 List Load Activation Profiles . . . . . . . 796
Get CPC Properties . . . . . . . . . . 648 Get Load Activation Profile Properties . . . . 798
Update CPC Properties . . . . . . . . . 656 Update Load Activation Profile Properties . . . 800
Start CPC . . . . . . . . . . . . . 657 Inventory service data . . . . . . . . . 802
Stop CPC. . . . . . . . . . . . . . 660 Group profile . . . . . . . . . . . . . 802
Activate CPC . . . . . . . . . . . . 662 Data model . . . . . . . . . . . . . 803
Deactivate CPC. . . . . . . . . . . . 664 List Group Profiles . . . . . . . . . . 804
Import Profiles . . . . . . . . . . . . 666 Get Group Profile Properties . . . . . . . 806

vi HMC Web Services API

 Level 04a

Update Group Profile Properties . . . . . . 808 Chapter 14. zBX infrastructure

Inventory service data . . . . . . . . . 809 elements . . . . . . . . . . . . . 881
Capacity records . . . . . . . . . . . . 810 zBX physical network overview . . . . . . . 881
Data model . . . . . . . . . . . . . 810 zBX infrastructure operations summary . . . . 882
List Capacity Records . . . . . . . . . 812 zBX object . . . . . . . . . . . . . . 883
Get Capacity Record Properties . . . . . . 813 Data model . . . . . . . . . . . . . 884
Inventory service data . . . . . . . . . 814 Operations . . . . . . . . . . . . . 891
List zBXs of a CPC . . . . . . . . . . 891
Chapter 12. Energy management . . . 817 List zBXs of an Ensemble . . . . . . . . 894
Groups . . . . . . . . . . . . . . . 818 Get zBX Properties . . . . . . . . . . 896
Special states . . . . . . . . . . . . . 819 Get EC/MCL Description of zBX (Node) . . . 899
Power saving . . . . . . . . . . . . . 820 Activate zBX (Node) . . . . . . . . . . 902
Group power saving . . . . . . . . . . 820 Deactivate zBX (Node) . . . . . . . . . 905
Power capping . . . . . . . . . . . . . 820 Get zBX (Node) Audit Log . . . . . . . . 907
Group capping . . . . . . . . . . . . 820 Get zBX (Node) Security Log . . . . . . . 909
Energy management operations summary . . . . 821 List zBX (Node) Hardware Messages . . . . 912
Energy Management for zBX (Node) object . . . 822 Get zBX (Node) Hardware Message Properties 915
Data model . . . . . . . . . . . . . 822 Delete zBX (Node) Hardware Message . . . . 917
Operations . . . . . . . . . . . . . 822 Inventory service data . . . . . . . . . 918
Set zBX (Node) Power Save . . . . . . . 822 zBX Top-of-Rack switches . . . . . . . . . 919
Set zBX (Node) Power Capping . . . . . . 824 Data model . . . . . . . . . . . . . 919
Energy Management for CPC object . . . . . . 827 Operations . . . . . . . . . . . . . 921
Data model . . . . . . . . . . . . . 827 List Top-of-Rack Switches of a zBX . . . . . 921
Operations . . . . . . . . . . . . . 827 Get Top-of-Rack Switch Properties . . . . . 924
Set CPC Power Save . . . . . . . . . . 827 Get Top-of-Rack Switch Port Details . . . . . 926
Set CPC Power Capping. . . . . . . . . 829 Update Top-of-Rack Switch Port Properties . . 928
Set zCPC Power Save . . . . . . . . . 832 Add MAC Filters to Top-of-Rack Switch Port 930
Set zCPC Power Capping . . . . . . . . 834 Remove MAC Filters from Top-of-Rack Switch
Get CPC Energy Management Data . . . . . 836 Port . . . . . . . . . . . . . . . 932
Get Energy Optimization Advice Summary . . 837 Add Top-of-Rack Switch Port to Virtual
Get Energy Optimization Advice Details . . . 843 Networks. . . . . . . . . . . . . . 934
Energy Management for BladeCenter object . . . 848 Remove Top-of-Rack Switch Port from the
Data model . . . . . . . . . . . . . 848 Virtual Networks . . . . . . . . . . . 936
Operations . . . . . . . . . . . . . 848 Rack object . . . . . . . . . . . . . . 938
Set BladeCenter Power Save . . . . . . . 848 Data model . . . . . . . . . . . . . 939
Set BladeCenter Power Capping . . . . . . 851 Operations . . . . . . . . . . . . . 939
Energy Management for Blade object . . . . . 853 List Racks of a zBX . . . . . . . . . . 939
Data model . . . . . . . . . . . . . 853 Get Rack Properties . . . . . . . . . . 941
Operations . . . . . . . . . . . . . 853 Inventory service data . . . . . . . . . 943
Set Blade Power Save. . . . . . . . . . 853 BladeCenter object. . . . . . . . . . . . 944
Set Blade Power Capping . . . . . . . . 855 Data model . . . . . . . . . . . . . 944
Operations . . . . . . . . . . . . . 947
Part 4. Ensemble and zBX List BladeCenters in a Rack. . . . . . . . 947
List BladeCenters in a zBX . . . . . . . . 949
management . . . . . . . . . . . 859 Get BladeCenter Properties . . . . . . . . 951
Activate BladeCenter . . . . . . . . . . 953
Chapter 13. Ensemble composition 861 Deactivate BladeCenter . . . . . . . . . 956
Ensemble composition operations summary . . . 861 Inventory service data . . . . . . . . . 958
Ensemble object . . . . . . . . . . . . 862 Blade object . . . . . . . . . . . . . . 959
Data model . . . . . . . . . . . . . 862 Data model . . . . . . . . . . . . . 959
Operations . . . . . . . . . . . . . 865 Operations . . . . . . . . . . . . . 964
List Ensembles . . . . . . . . . . . . 865 List Blades in a BladeCenter . . . . . . . 964
Get Ensemble Properties. . . . . . . . . 867 List Blades in a zBX . . . . . . . . . . 966
Update Ensemble Properties . . . . . . . 869 Get Blade Properties . . . . . . . . . . 969
List Ensemble Nodes . . . . . . . . . . 871 Activate a Blade . . . . . . . . . . . 973
Get Node Properties . . . . . . . . . . 873 Deactivate a Blade. . . . . . . . . . . 975
Add Node to Ensemble . . . . . . . . . 875 Create IEDN Interface for a DataPower XI50z
Remove Node from Ensemble . . . . . . . 878 Blade . . . . . . . . . . . . . . . 977
Inventory service data . . . . . . . . . 879 Delete IEDN Interface for a DataPower XI50z
Usage notes . . . . . . . . . . . . . 880 Blade . . . . . . . . . . . . . . . 980
Inventory service data . . . . . . . . . 981

Contents vii
 Level 04a

Chapter 15. Virtualization Data model. . . . . . . . . . . . . 1142

management. . . . . . . . . . . . 985 Operations . . . . . . . . . . . . . 1143
Virtualization host operations summary . . . . 985 List Storage Resources . . . . . . . . . 1143
Virtual server operations summary . . . . . . 986 Get Storage Resource Properties . . . . . . 1146
Virtualization Host object . . . . . . . . . 987 Create Storage Resource . . . . . . . . 1147
Data model . . . . . . . . . . . . . 987 Update Storage Resource Properties . . . . 1149
Operations . . . . . . . . . . . . . 998 Delete Storage Resource . . . . . . . . 1151
List Virtualization Hosts of a zBX (Node) . . . 998 Export World Wide Port Names List . . . . 1153
List Virtualization Hosts of a Node. . . . . 1000 Import Storage Access List . . . . . . . 1155
List Virtualization Hosts of an Ensemble . . . 1003 List Virtualization Host Storage Resources of a
List Virtualization Hosts of a CPC . . . . . 1005 Storage Resource . . . . . . . . . . . 1157
Get Virtualization Host Properties . . . . . 1008 Inventory service data . . . . . . . . . 1159
Update Virtualization Host Properties . . . . 1013 Virtualization Host Storage Resource object . . . 1160
List Virtual Switches . . . . . . . . . 1015 Data model. . . . . . . . . . . . . 1160
Get Virtual Switch Properties. . . . . . . 1016 Operations . . . . . . . . . . . . . 1162
Create IEDN Virtual Switch . . . . . . . 1019 List Virtualization Host HBA Ports . . . . . 1162
Create QDIO Virtual Switch . . . . . . . 1022 List Virtualization Host Storage Resources . . 1164
Get Switch Controllers . . . . . . . . . 1025 Get Virtualization Host Storage Resource
Update Virtual Switch . . . . . . . . . 1027 Properties . . . . . . . . . . . . . 1167
Delete Virtual Switch . . . . . . . . . 1031 Create Virtualization Host Storage Resource 1171
Activating a Virtualization Host . . . . . . 1032 Delete Virtualization Host Storage Resource 1174
Deactivating a Virtualization Host . . . . . 1033 Add Virtualization Host Storage Resource
SMAPI Error Response Body . . . . . . . 1033 Paths . . . . . . . . . . . . . . . 1176
Inventory service data . . . . . . . . . 1034 Remove Virtualization Host Storage Resource
Virtual Server Object . . . . . . . . . . 1036 Paths . . . . . . . . . . . . . . . 1179
Data model. . . . . . . . . . . . . 1037 Discover Virtualization Host Storage Resources 1182
Operations . . . . . . . . . . . . . 1062 List Virtual Disks of a Virtualization Host
List Virtual Servers of a zBX (Node) . . . . 1063 Storage Resource . . . . . . . . . . . 1184
List Virtual Servers of a Node . . . . . . 1065 Notifications . . . . . . . . . . . . 1186
List Virtual Servers of an Ensemble. . . . . 1067 Inventory service data . . . . . . . . . 1186
List Virtual Servers of a CPC . . . . . . . 1070 Virtualization Host Storage Group object . . . . 1187
List Virtual Servers of a Virtualization Host 1073 Data model. . . . . . . . . . . . . 1187
Create Virtual Server . . . . . . . . . 1075 Operations . . . . . . . . . . . . . 1188
Delete Virtual Server . . . . . . . . . 1080 List Virtualization Host Storage Groups . . . 1188
Get Virtual Server Properties . . . . . . . 1082 Get Virtualization Host Storage Group
Update Virtual Server Properties . . . . . 1090 Properties . . . . . . . . . . . . . 1190
Create Network Adapter . . . . . . . . 1095 List Virtualization Host Storage Resources in a
Delete Network Adapter . . . . . . . . 1098 Virtualization Host Storage Group . . . . . 1192
Get Network Adapter Properties . . . . . 1099 Add Virtualization Host Storage Resource to
Update Network Adapter . . . . . . . . 1101 Virtualization Host Storage Group . . . . . 1194
Reorder Network Adapter . . . . . . . . 1104 Remove Virtualization Host Storage Resource
Create Virtual Disk . . . . . . . . . . 1106 from Virtualization Host Storage Group . . . 1196
Delete Virtual Disk . . . . . . . . . . 1110 Notifications . . . . . . . . . . . . 1197
Get Virtual Disk Properties . . . . . . . 1112 Inventory service data . . . . . . . . . 1198
Update Virtual Disk Properties . . . . . . 1114 Usage notes . . . . . . . . . . . . 1198
Reorder Virtual Disks . . . . . . . . . 1117
Activate Virtual Server . . . . . . . . . 1119 Chapter 17. Virtual network
Deactivate Virtual Server . . . . . . . . 1121 management . . . . . . . . . . . 1199
Mount Virtual Media . . . . . . . . . 1124 Virtual network management operations summary 1199
Mount Virtual Media Image . . . . . . . 1126 Virtual Network object . . . . . . . . . . 1199
Unmount Virtual Media . . . . . . . . 1128 Data model. . . . . . . . . . . . . 1200
Migrate Virtual Server . . . . . . . . . 1130 List Virtual Networks . . . . . . . . . 1200
Initiate Virtual Server Dump . . . . . . . 1132 Get Virtual Network Properties . . . . . . 1202
Inventory service data . . . . . . . . . 1133 Update Virtual Network Properties. . . . . 1203
Create Virtual Network. . . . . . . . . 1206
Chapter 16. Storage management 1139 Delete Virtual Network. . . . . . . . . 1208
Terms . . . . . . . . . . . . . . . 1139 List Members of a Virtual Network. . . . . 1210
Object model overview . . . . . . . . . . 1140 Inventory service data . . . . . . . . . 1212
Storage management operations summary . . . 1140
Storage Resource object. . . . . . . . . . 1142

viii HMC Web Services API

 Level 04a

Chapter 18. Workload resource Generate Service Class Virtual Server Topology
group management . . . . . . . . 1215 Report . . . . . . . . . . . . . . 1324
Overview . . . . . . . . . . . . . . 1215 Generate Load Balancing Report . . . . . 1332
Workload resource group operations summary 1216 Workload Element Group object . . . . . . . 1334
Workload Resource Group object . . . . . . 1219 Data model. . . . . . . . . . . . . 1334
Data model. . . . . . . . . . . . . 1219 List Workload Element Groups of an Ensemble 1337
List Workload Resource Groups of an Get Workload Element Group Properties . . . 1338
Ensemble . . . . . . . . . . . . . 1224 Create Workload Element Group . . . . . 1339
Get Workload Resource Group Properties . . 1226 Delete Workload Element Group . . . . . 1342
Create Workload Resource Group . . . . . 1228 Update Workload Element Group . . . . . 1343
Delete Workload Resource Group . . . . . 1231 List Virtual Servers of a Workload Element
Update Workload Resource Group . . . . . 1232 Group . . . . . . . . . . . . . . 1344
List Virtual Servers of a Workload Resource Add Virtual Server to a Workload Element
Group . . . . . . . . . . . . . . 1234 Group . . . . . . . . . . . . . . 1345
Add Virtual Server to a Workload Resource Remove Virtual Server from a Workload
Group . . . . . . . . . . . . . . 1237 Element Group . . . . . . . . . . . 1347
Remove Virtual Server from a Workload Availability Policy object . . . . . . . . . 1348
Resource Group . . . . . . . . . . . 1239 Data model. . . . . . . . . . . . . 1349
List Groups of Virtual Servers of a Workload List Availability Policies . . . . . . . . 1351
Resource Group . . . . . . . . . . . 1241 Get Availability Policy Properties . . . . . 1353
Add Group of Virtual Servers to a Workload Create Availability Policy . . . . . . . . 1354
Resource Group . . . . . . . . . . . 1243 Delete Availability Policy . . . . . . . . 1356
Remove Group of Virtual Servers from a Update Availability Policy . . . . . . . . 1357
Workload Resource Group . . . . . . . 1245 Activate Availability Policy . . . . . . . 1359
List Workload Element Groups of a Workload Ensemble Availability Management reports . . . 1360
Resource Group . . . . . . . . . . . 1247 Generate Workload Resource Groups Report
Add Workload Element Group to a Workload (Ensemble Availability Management) . . . . 1362
Resource Group . . . . . . . . . . . 1248 Generate Workload Resource Group
Remove Workload Element Group from a Availability Status Report . . . . . . . . 1365
Workload Resource Group . . . . . . . 1250 Generate Virtual Servers Report (Ensemble
Performance Policy object . . . . . . . . . 1252 Availability Management) . . . . . . . . 1370
Data model. . . . . . . . . . . . . 1252 Generate Availability Status Report. . . . . 1373
Notifications of property changes to Get Performance Management Velocity Level
performance policies . . . . . . . . . 1256 Range Mappings . . . . . . . . . . . . 1375
List Performance Policies . . . . . . . . 1257 Inventory service data . . . . . . . . . . 1377
Get Performance Policy Properties . . . . . 1259
Create Performance Policy. . . . . . . . 1262 Part 5. Appendixes . . . . . . . 1383
Delete Performance Policy. . . . . . . . 1264
Update Performance Policy . . . . . . . 1266 Appendix A. XML document
Activate Performance Policy . . . . . . . 1269
Import Performance Policy . . . . . . . 1270
structure of a performance policy . . 1385
Export Performance Policy . . . . . . . 1272 XML structure of a ServiceClasses element . . . 1385
Performance management reports . . . . . . 1275 Sample XML document for a performance policy 1389
Generate Workload Resource Groups Report
(Performance Management) . . . . . . . 1276 Appendix B. Enum values for a type
Generate Workload Resource Group of managed objects within User
Performance Index Report. . . . . . . . 1280 Roles . . . . . . . . . . . . . . 1393
Generate Workload Resource Group Resource
Adjustments Report . . . . . . . . . . 1283
Appendix C. Enum values for the
Generate Virtual Servers Report . . . . . . 1287
Generate Virtual Server CPU Utilization Report 1291 User Role object . . . . . . . . . 1395
Generate Virtual Server Resource Adjustments
Report . . . . . . . . . . . . . . 1294 Appendix D. Enum values for the
Generate Hypervisor Report . . . . . . . 1299 Task object . . . . . . . . . . . . 1397
Generate Hypervisor Resource Adjustments
Report . . . . . . . . . . . . . . 1307 Appendix E. Notices . . . . . . . . 1405
Generate Service Classes Report . . . . . . 1311
Trademarks . . . . . . . . . . . . . 1406
Generate Service Class Resource Adjustments
Class A Notices . . . . . . . . . . . . 1407
Report . . . . . . . . . . . . . . 1314
Generate Service Class Hops Report . . . . 1319
Index . . . . . . . . . . . . . . 1411

Contents ix
 Level 04a

x HMC Web Services API

 Level 04a

Figures
1. Logon: Request . . . . . . . . . . .
74 55. Get Virtual Function Properties: Response 211
2. Logon: Response . . . . . . . . . . .
74 56. Update Virtual Function Properties: Request 213
3. Establish Shared Secret Key: Request . . . .
76 57. Update Virtual Function Properties: Response 213
4. Establish Shared Secret Key: Response . . .
76 58. Create NIC: Request . . . . . . . . . 216
5. Logoff: Request . . . . . . . . . . .
77 59. Create NIC: Response . . . . . . . . . 217
6. Logoff: Response . . . . . . . . . . .
77 60. Delete NIC: Request . . . . . . . . . 218
7. Get Notification Topics: Request . . . . .
79 61. Delete NIC: Response . . . . . . . . . 218
8. Get Notification Topics: Response . . . . .
79 62. Get NIC Properties: Request . . . . . . 220
9. Query Job Status: Request. . . . . . . .
83 63. Get NIC Properties: Response . . . . . . 220
10. Query Job Status: Response . . . . . . .
83 64. Update NIC Properties: Request . . . . . 223
11. Delete Completed Job Status: Request . . . .
84 65. Update NIC Properties: Response . . . . . 223
12. Delete Completed Job Status: Response 84 66. Increase Crypto Configuration: Request 226
13. Cancel Job: Request . . . . . . . . . . 86 67. Increase Crypto Configurations: Response 226
14. Cancel Job: Response . . . . . . . . . 86 68. Change Crypto Domain Configuration:
15. Get Inventory: Request. . . . . . . . . 93 Request . . . . . . . . . . . . . 228
16. Get Inventory: Response . . . . . . . . 93 69. Change Crypto Domain Configuration:
17. Create Metrics Context: Request. . . . . . 96 Response . . . . . . . . . . . . . 228
18. Create Metrics Context: Response . . . . . 97 70. Decrease Crypto Configuration: Request 230
19. Get Metrics: Request . . . . . . . . . 100 71. Decrease Crypto Configuration: Response 231
20. Get Metrics: Response . . . . . . . . 101 72. Mount ISO Image: Request . . . . . . . 232
21. Delete Metrics Context: Request . . . . . 102 73. Mount ISO Image: Response . . . . . . 232
22. Delete Metrics Context: Response . . . . . 102 74. Unmount ISO Image: Request . . . . . . 234
23. List Partitions of a CPC: Request . . . . . 166 75. Unmount ISO Image: Response . . . . . 234
24. List Partitions of a CPC: Response . . . . 167 | 76. Attach Storage Group to Partition: Request 236
25. List Permitted Partitions: Request . . . . . 169 | 77. Attach Storage Group to Partition: Response 236
26. List Permitted Partitions: Response . . . . 170 | 78. Detach Storage Group from Partition: Request 238
27. Create Partition: Request . . . . . . . . 175 | 79. Detach Storage Group from Partition:
28. Create Partition: Response . . . . . . . 175 | Response . . . . . . . . . . . . . 239
29. Delete Partition: Request . . . . . . . . 176 80. Create HBA: Request . . . . . . . . . 241
30. Delete Partition: Response . . . . . . . 177 81. Create HBA: Response . . . . . . . . 241
31. Delete Partition Asynchronously: Request 179 82. Delete HBA: Request . . . . . . . . . 243
32. Delete Partition Asynchronously: Response 179 83. Delete HBA: Response . . . . . . . . 243
33. Get Partition Properties: Request . . . . . 180 84. Update HBA Properties: Request . . . . . 245
34. Get Partition Properties: Response (Part 1) 181 85. Update HBA Properties: Response . . . . 245
35. Get Partition Properties: Response (Part 2) 182 86. Get HBA Properties: Request . . . . . . 246
36. Update Partition Properties: Request 186 87. Get HBA Properties: Response . . . . . . 247
37. Update Partition Properties: Response 186 88. Reassign Storage Adapter Port: Request 249
38. Update Partition Properties Asynchronously: 89. Reassign Storage Adapter Port: Response 249
Request . . . . . . . . . . . . . 190 90. Send OS Command: Request . . . . . . 250
39. Update Partition Properties Asynchronously: 91. Send OS Command: Response . . . . . . 251
Response . . . . . . . . . . . . . 190 92. Open OS Message Channel: Request . . . . 252
40. Start Partition: Request . . . . . . . . 193 93. Open OS Message Channel: Response 253
41. Start Partition: Response . . . . . . . . 193 94. List OS Messages of a Partition: Request 255
42. Stop Partition: Request . . . . . . . . 195 95. List OS Messages of a Partition: Response 256
43. Stop Partition: Response . . . . . . . . 195 96. Get ASCII Console WebSocket URI: Request 258
44. Dump Partition: Request . . . . . . . . 198 97. Get ASCII Console WebSocket URI: Response 259
45. Dump Partition: Response . . . . . . . 199 98. Partition object: Sample inventory data -
| 46. Start Dump Program: Request . . . . . . 203 Response (Part 1) . . . . . . . . . . 260
| 47. Start Dump Program: Response . . . . . 203 99. Partition object: Sample inventory data -
48. Perform PSW Restart: Request . . . . . . 205 Response (Part 2) . . . . . . . . . . 261
49. Perform PSW Restart: Response . . . . . 205 100. Partition object: Sample inventory data -
50. Create Virtual Function: Request . . . . . 207 Response (Part 3) . . . . . . . . . . 261
51. Create Virtual Function: Response . . . . 208 101. List Adapters of a CPC: Request . . . . . 275
52. Delete Virtual Function: Request . . . . . 209 102. List Adapters of a CPC: Response. . . . . 275
53. Delete Virtual Function: Response. . . . . 209 103. Get Adapter Properties: Request . . . . . 276
54. Get Virtual Function Properties: Request 211 104. Get Adapter Properties: Response . . . . . 277

© Copyright IBM Corp. 2017, 2018 xi

 Level 04a

105. Update Adapter Properties: Request . . . . 279 | 160. List Storage Fabrics: Request . . . . . . 339
106. Update Adapter Properties: Response 279 | 161. List Storage Fabrics: Response . . . . . . 339
107. Change Crypto Type: Request . . . . . . 281 | 162. Create Storage Fabric: Request . . . . . . 341
108. Change Crypto Type: Response . . . . . 281 | 163. Create Storage Fabric: Response . . . . . 341
109. Create Hipersocket: Request . . . . . . 283 | 164. Delete Storage Fabric: Request . . . . . . 343
110. Create Hipersocket: Response . . . . . . 284 | 165. Delete Storage Fabric: Response . . . . . 343
111. Delete Hipersocket: Request . . . . . . 285 | 166. Get Storage Fabric Properties: Request 344
112. Delete Hipersocket: Response . . . . . . 285 | 167. Get Storage Fabric Properties: Response 344
113. Get Partitions Assigned to Adapter: Request 287 | 168. Update Storage Fabric Properties: Request 346
114. Get Partitions Assigned to Adapter: Response 287 | 169. Update Storage Fabric Properties: Response 346
115. Get Network Port Properties: Request 289 | 170. Storage Fabric object: Sample inventory data -
116. Get Network Port Properties: Response 289 | Response . . . . . . . . . . . . . 347
117. Update Network Port Properties: Request 291 | 171. List Storage Switches of a Storage Site:
118. Update Network Port Properties: Response 291 | Request . . . . . . . . . . . . . 350
119. Get Storage Port Properties: Request . . . . 292 | 172. List Storage Switches of a Storage Site:
120. Get Storage Port Properties: Response 292 | Response . . . . . . . . . . . . . 350
121. Update Storage Port Properties: Request 294 | 173. List Storage Switches of a Storage Fabric:
122. Update Storage Port Properties: Response 294 | Request . . . . . . . . . . . . . 352
| 123. Change Adapter Type: Request . . . . . 296 | 174. List Storage Switches of a Storage Fabric:
| 124. Change Adapter Type: Response . . . . . 296 | Response . . . . . . . . . . . . . 353
125. Adapter object: Sample inventory data 297 | 175. Define Storage Switch: Request . . . . . 355
126. List Virtual Switches of a CPC: Request 301 | 176. Define Storage Switch: Response . . . . . 355
127. List Virtual Switches of a CPC: Response 301 | 177. Undefine Storage Switch: Request. . . . . 357
128. Get Virtual Switch Properties: Request 302 | 178. Undefine Storage Switch: Response . . . . 357
129. Get Virtual Switch Properties: Response 303 | 179. Get Storage Switch Properties: Request 358
130. Get Connected VNICs of a Virtual Switch: | 180. Get Storage Switch Properties: Response 358
Request . . . . . . . . . . . . . 304 | 181. Update Storage Switch Properties: Request 360
131. Get Connected VNICs of a Virtual Switch: | 182. Update Storage Switch Properties: Response 360
Response . . . . . . . . . . . . . 304 | 183. Move Storage Switch to Storage Site: Request 362
132. Update Virtual Switch Properties: Request 306 | 184. Move Storage Switch to Storage Site:
133. Update Virtual Switch Properties: Response 306 | Response . . . . . . . . . . . . . 362
134. Virtual Switch object: Sample inventory data - | 185. Move Storage Switch to Storage Fabric:
Response . . . . . . . . . . . . . 307 | Request . . . . . . . . . . . . . 364
135. List Capacity Groups of a CPC: Request 310 | 186. Move Storage Switch to Storage Fabric:
136. List Capacity Groups of a CPC: Response 310 | Response . . . . . . . . . . . . . 364
137. Create Capacity Group: Request . . . . . 313 | 187. Storage Switch object: Sample inventory data
138. Create Capacity Group: Response . . . . . 313 | - Response . . . . . . . . . . . . 365
139. Delete Capacity Group: Request . . . . . 314 | 188. List Storage Subsystems of a Storage Site:
140. Delete Capacity Group: Response . . . . . 315 | Request . . . . . . . . . . . . . 368
141. Get Capacity Group Properties: Request 316 | 189. List Storage Subsystems of a Storage Site:
142. Get Capacity Group Properties: Response 316 | Response . . . . . . . . . . . . . 368
143. Add Partition to Capacity Group: Request 318 | 190. Define Storage Subsystem: Request . . . . 370
144. Add Partition to Capacity Group: Response 319 | 191. Define Storage Subsystem: Response 370
145. Remove Partition from Capacity Group: | 192. Undefine Storage Subsystem: Request 372
Request . . . . . . . . . . . . . 320 | 193. Undefine Storage Subsystem: Response 372
146. Remove Partition from Capacity Group: | 194. Get Storage Subsystem Properties: Request 373
Response . . . . . . . . . . . . . 321 | 195. Get Storage Subsystem Properties: Response 374
147. Update Capacity Group Properties: Request 322 | 196. Update Storage Subsystem Properties:
148. Update Capacity Group Properties: Response 323 | Request . . . . . . . . . . . . . 376
| 149. List Storage Sites: Request . . . . . . . 326 | 197. Update Storage Subsystem Properties:
| 150. List Storage Sites: Response . . . . . . . 327 | Response . . . . . . . . . . . . . 376
| 151. Create Storage Site: Request. . . . . . . 329 | 198. Move Storage Subsystem to Storage Site:
| 152. Create Storage Site: Response . . . . . . 329 | Request . . . . . . . . . . . . . 378
| 153. Delete Storage Site: Request. . . . . . . 331 | 199. Move Storage Subsystem to Storage Site:
| 154. Delete Storage Site: Response . . . . . . 331 | Response . . . . . . . . . . . . . 378
| 155. Get Storage Site Properties: Request . . . . 332 | 200. Add Connection Endpoint: Request . . . . 380
| 156. Get Storage Site Properties: Response 333 | 201. Add Connection Endpoint: Response 380
| 157. Update Storage Site Properties: Request 335 | 202. Remove Connection Endpoint: Request 382
| 158. Update Storage Site Properties: Response 335 | 203. Remove Connection Endpoint: Response 382
| 159. Storage Site object: Sample inventory data - | 204. Storage Subsystem object: Sample inventory
| Response . . . . . . . . . . . . . 336 | data - Response . . . . . . . . . . . 383

xii HMC Web Services API

 Level 04a

| 205. List Storage Control Units of a Storage | 252. Get Virtual Storage Resource Properties:
| Subsystem: Request . . . . . . . . . 388 | Request . . . . . . . . . . . . . 462
| 206. List Storage Control Units of a Storage | 253. Get Virtual Storage Resource Properties:
| Subsystem: Response . . . . . . . . . 388 | Response . . . . . . . . . . . . . 463
| 207. Define Storage Control Unit: Request 390 | 254. Update Virtual Storage Resource Properties:
| 208. Define Storage Control Unit: Response 390 | Request . . . . . . . . . . . . . 465
| 209. Undefine Storage Control Unit: Request 392 | 255. Update Virtual Storage Resource Properties:
| 210. Undefine Storage Control Unit: Response 392 | Response . . . . . . . . . . . . . 465
| 211. Get Storage Control Unit Properties: Request 393 | 256. Get Partitions for a Storage Group: Request 467
| 212. Get Storage Control Unit Properties: Response 394 | 257. Get Partitions for a Storage Group: Response 467
| 213. Update Storage Control Unit Properties: | 258. Validate LUN Path: Request . . . . . . 469
| Request . . . . . . . . . . . . . 396 | 259. Validate LUN Path: Response . . . . . . 469
| 214. Update Storage Control Unit Properties: | 260. Storage Group object: Sample inventory data
| Response . . . . . . . . . . . . . 396 | - Response (Part 1) . . . . . . . . . . 471
| 215. Add Volume Range: Request . . . . . . 398 | 261. Storage Group object: Sample inventory data
| 216. Add Volume Range: Response . . . . . . 398 | - Response (Part 2) . . . . . . . . . . 473
| 217. Remove Volume Range: Request . . . . . 399 262. Get Console Properties: Request . . . . . 489
| 218. Remove Volume Range: Response. . . . . 400 263. Get Console Properties: Response (Part 1) 490
| 219. Create Storage Path: Request . . . . . . 402 264. Get Console Properties: Response (Part 2) 491
| 220. Create Storage Path: Response . . . . . . 402 265. Get Console Properties: Response (Part 3) 492
| 221. Delete Storage Path: Request . . . . . . 404 266. Shutdown Console: Request. . . . . . . 496
| 222. Delete Storage Path: Response . . . . . . 404 267. Shutdown Console: Response . . . . . . 496
| 223. Get Storage Path Properties: Request 405 268. Reorder User Patterns: Request . . . . . 498
| 224. Get Storage Path Properties: Response 405 269. Reorder User Patterns: Response . . . . . 498
| 225. Update Storage Path Properties: Request 407 270. Get Console Audit Log: Request . . . . . 500
| 226. Update Storage Path Properties: Response 408 271. Get Console Audit Log: Response. . . . . 501
| 227. Storage Control Unit object: Sample inventory 272. Get Console Security Log: Request . . . . 503
| data - Response . . . . . . . . . . . 409 273. Get Console Security Log: Response (Part 1) 504
| 228. List Storage Groups: Request . . . . . . 425 274. Get Console Security Log: Response (Part 2) 505
| 229. List Storage Groups: Response . . . . . . 426 275. List Console Hardware Messages: Request 507
| 230. Create Storage Group: Request . . . . . . 430 276. List Console Hardware Messages: Response 507
| 231. Create Storage Group: Response . . . . . 430 277. Get Console Hardware Message Properties:
| 232. Delete Storage Group: Request . . . . . . 433 Request . . . . . . . . . . . . . 508
| 233. Delete Storage Group: Response . . . . . 433 278. Get Console Hardware Message Properties:
| 234. Get Storage Group Properties: Request 434 Response . . . . . . . . . . . . . 509
| 235. Get Storage Group Properties: Response 435 279. Delete Console Hardware Message: Request 510
| 236. Modify Storage Group Properties: Request 443 280. Delete Console Hardware Message: Response 510
| 237. Modify Storage Group Properties: Response 443 281. List Unmanaged CPCs: Request . . . . . 512
| 238. Add Candidate Adapter Ports to an FCP 282. List Unmanaged CPCs: Response . . . . . 512
| Storage Group: Request . . . . . . . . 445 283. List Unmanaged zBX Nodes: Request 514
| 239. Add Candidate Adapter Ports to an FCP 284. List Unmanaged zBX Nodes: Response 514
| Storage Group: Response . . . . . . . 446 285. Get Mobile App Preferences: Request 515
| 240. Remove Candidate Adapter Ports from an 286. Get Mobile App Preferences: Response 515
| FCP Storage Group: Request . . . . . . 448 287. Set Mobile App Preferences: Request 517
| 241. Remove Candidate Adapter Ports from an 288. Set Mobile App Preferences: Response 517
| FCP Storage Group: Response . . . . . . 448 289. Get CPC Notification Preferences for Device:
| 242. List Storage Volumes of a Storage Group: Request . . . . . . . . . . . . . 520
| Request . . . . . . . . . . . . . 450 290. Get CPC Notification Preferences for Device:
| 243. List Storage Volumes of a Storage Group: Response . . . . . . . . . . . . . 521
| Response . . . . . . . . . . . . . 451 291. Update CPC Notification Preferences for
| 244. Get Storage Volume Properties: Request 453 Device: Request . . . . . . . . . . . 524
| 245. Get Storage Volume Properties: Response 453 292. Update CPC Notification Preferences for
| 246. Fulfill FICON Storage Volume: Request 456 Device: Response . . . . . . . . . . 525
| 247. Fulfill FICON Storage Volume: Response 456 293. Console object: Sample inventory data (Part
| 248. Fulfill FCP Storage Volume: Request . . . . 458 1) . . . . . . . . . . . . . . . 526
| 249. Fulfill FCP Storage Volume: Response 458 294. Console object: Sample inventory data (Part
| 250. List Virtual Storage Resources of a Storage 2) . . . . . . . . . . . . . . . 527
| Group: Request . . . . . . . . . . . 461 295. Console object: Sample inventory data (Part
| 251. List Virtual Storage Resources of a Storage 3) . . . . . . . . . . . . . . . 528
| Group: Response . . . . . . . . . . 461 296. Console object: Sample inventory data (Part
4) . . . . . . . . . . . . . . . 529

Figures xiii
 Level 04a

297. List Users: Request. . . . . . . . . . 536 357. Get LDAP Server Definition Properties:
298. List Users: Response . . . . . . . . . 537 Response . . . . . . . . . . . . . 609
299. Get User Properties: Request . . . . . . 538 358. Update LDAP Server Definition Properties:
300. Get User Properties: Response . . . . . . 539 Request . . . . . . . . . . . . . 610
301. Update User Properties: Request . . . . . 542 359. Update LDAP Server Definition Properties:
302. Update User Properties: Response . . . . 542 Response . . . . . . . . . . . . . 611
303. Add User Role to User: Request . . . . . 544 360. Create LDAP Server Definition: Request 613
304. Add User Role to User: Response . . . . . 544 361. Create LDAP Server Definition: Response 613
305. Remove User Role from User: Request 546 362. Delete LDAP Server Definition: Request 614
306. Remove User Role from User: Response 546 363. Delete LDAP Server Definition: Response 614
307. Create User: Request . . . . . . . . . 549 364. LDAP Server Definition object: Sample
308. Create User: Response . . . . . . . . 549 inventory data . . . . . . . . . . . 615
309. Delete User: Request . . . . . . . . . 550 365. List Custom Groups: Request . . . . . . 619
310. Delete User: Response . . . . . . . . 551 366. List Custom Groups: Response. . . . . . 619
311. User object: Sample inventory data . . . . 552 367. Get Custom Group Properties: Request 620
312. List User Roles: Request . . . . . . . . 557 368. Get Custom Group Properties: Response 620
313. List User Roles: Response . . . . . . . 558 369. Create Custom Group: Request . . . . . 622
314. Get User Role Properties: Request. . . . . 559 370. Create Custom Group: Response . . . . . 622
315. Get User Role Properties: Response . . . . 560 371. Delete Custom Group: Request . . . . . 623
316. Update User Role Properties: Request 562 372. Delete Custom Group: Response . . . . . 623
317. Update User Role Properties: Response 562 373. Add Member to Custom Group: Request 625
318. Add Permission to User Role: Request 564 374. Add Member to Custom Group: Response 625
319. Add Permission to User Role: Response 565 375. Remove Member from Custom Group:
320. Remove Permission from User Role: Request 567 Request . . . . . . . . . . . . . 626
321. Remove Permission from User Role: Response 567 376. Remove Member from Custom Group:
322. Create User Role: Request . . . . . . . 569 Response . . . . . . . . . . . . . 627
323. Create User Role: Response . . . . . . . 569 377. List Custom Group Members: Request 628
324. Delete User Role: Request . . . . . . . 570 378. List Custom Group Members: Response 628
325. Delete User Role: Response . . . . . . . 571 379. List CPC Objects: Request . . . . . . . 645
326. User Role object: Sample inventory data 572 380. List CPC Objects: Response . . . . . . . 646
327. List Tasks: Request . . . . . . . . . . 574 381. List Ensemble CPC Objects: Request . . . . 648
328. List Tasks: Response . . . . . . . . . 574 382. List Ensemble CPC Objects: Response 648
329. Get Task Properties: Request . . . . . . 575 383. Get CPC Properties: Request . . . . . . 650
330. Get Task Properties: Response . . . . . . 576 384. Get CPC Properties: Response (Part 1) 651
331. Task object: Sample inventory data . . . . 576 385. Get CPC Properties: Response (Part 2) 652
332. List User Patterns: Request . . . . . . . 580 386. Get CPC Properties: Response (Part 3) 653
333. List User Patterns: Response . . . . . . 580 387. Get CPC Properties: Response (Part 4) 654
334. Get User Pattern Properties: Request 581 388. Get CPC Properties: Response (Part 5) 655
335. Get User Pattern Properties: Response 582 389. Get CPC Properties: Response (Part 6) 656
336. Update User Pattern Properties: Request 584 390. Set Auto-Start List: Request . . . . . . . 671
337. Update User Pattern Properties: Response 584 391. Set Auto-Start List: Response . . . . . . 671
338. Create User Pattern: Request . . . . . . 586 392. Get CPC Audit Log: Request . . . . . . 684
339. Create User Pattern: Response . . . . . . 586 393. Get CPC Audit Log: Response . . . . . . 684
340. Delete User Pattern: Request . . . . . . 587 394. Get CPC Security Log: Request . . . . . 686
341. Delete User Pattern: Response . . . . . . 587 395. Get CPC Security Log: Response . . . . . 687
342. User Pattern object: Sample inventory data 588 396. List CPC Hardware Messages: Request 689
343. List Password Rules: Request . . . . . . 593 397. List CPC Hardware Messages: Response 689
344. List Password Rules: Response. . . . . . 593 398. Get CPC Hardware Message Properties:
345. Get Password Rule Properties: Request 595 Request . . . . . . . . . . . . . 691
346. Get Password Rule Properties: Response 595 399. Get CPC Hardware Message Properties:
347. Update Password Rule Properties: Request 597 Response . . . . . . . . . . . . . 691
348. Update Password Rule Properties: Response 597 400. Delete CPC Hardware Message: Request 693
349. Create Password Rule: Request . . . . . 599 401. Delete CPC Hardware Message: Response 693
350. Create Password Rule: Response . . . . . 599 402. Export WWPN List: Request . . . . . . 695
351. Delete Password Rule: Request . . . . . 600 403. Export WWPN List: Response . . . . . . 695
352. Delete Password Rule: Response . . . . . 600 | 404. Import DPM Configuration: Request (Part 1) 698
353. Password Rule object: Sample inventory data 602 | 405. Import DPM Configuration: Request (Part 2) 699
354. List LDAP Server Definitions: Request 606 | 406. Import DPM Configuration: Request (Part 3) 700
355. List LDAP Server Definitions: Response 607 | 407. Import DPM Configuration: Request (Part 4) 701
356. Get LDAP Server Definition Properties: | 408. Import DPM Configuration: Request (Part 5) 702
Request . . . . . . . . . . . . . 608 | 409. Import DPM Configuration: Response 703

xiv HMC Web Services API

 Level 04a

410. List Logical Partitions of CPC: Request 721 450. Get Energy Optimization Advice Summary:
411. List Logical Partitions of CPC: Response 722 Response (Part 3) . . . . . . . . . . 842
412. List Permitted Logical Partitions: Request 724 451. Get Energy Optimization Advice Summary:
413. List Permitted Logical Partitions: Response 725 Response (Part 4) . . . . . . . . . . 843
414. Get Logical Partition Properties: Request 727 452. Get Energy Optimization Advice Details:
415. Get Logical Partition Properties: Response Request . . . . . . . . . . . . . 848
(Part 1) . . . . . . . . . . . . . 728 453. Get Energy Optimization Advice Details:
416. Get Logical Partition Properties: Response Response . . . . . . . . . . . . . 848
(Part 2) . . . . . . . . . . . . . 729 454. List Ensembles: Request . . . . . . . . 867
417. Send OS Command: Request . . . . . . 747 455. List Ensembles: Response . . . . . . . 867
418. Send OS Command: Response . . . . . . 747 456. Get Ensemble Properties: Request . . . . . 868
419. Open OS Message Channel: Request . . . . 749 457. Get Ensemble Properties: Response . . . . 869
420. Open OS Message Channel: Response 749 458. Update Ensemble Properties: Request 871
421. List OS Messages of a Logical Partition: 459. Update Ensemble Properties: Response 871
Request . . . . . . . . . . . . . 752 460. List Ensemble Nodes: Request . . . . . . 873
422. List OS Messages of a Logical Partition: 461. List Ensemble Nodes: Response . . . . . 873
Response . . . . . . . . . . . . . 752 462. Get Node Properties: Request . . . . . . 875
423. List Managed Virtual Machines of a Logical 463. Get Node Properties: Response . . . . . 875
Partition: Request . . . . . . . . . . 759 464. Ensemble object: Sample inventory data 880
424. List Managed Virtual Machines of a Logical 465. List zBXs of a CPC: Request . . . . . . 893
Partition: Response . . . . . . . . . 760 466. List zBXs of a CPC: Response . . . . . . 893
425. List Reset Activation Profiles: Request 763 467. List zBXs of an Ensemble: Request . . . . 895
426. List Reset Activation Profiles: Response 763 468. List zBXs of an Ensemble: Response . . . . 896
427. Get Reset Activation Profile Properties: 469. Get zBX Properties: Request . . . . . . 897
Request . . . . . . . . . . . . . 765 470. Get zBX Properties: Response (Part 1) 898
428. Get Reset Activation Profile Properties: 471. Get zBX Properties: Response (Part 2) 899
Response . . . . . . . . . . . . . 765 472. Get EC/MCL Description of zBX (Node):
429. List Image Activation Profiles: Request 787 Request . . . . . . . . . . . . . 900
430. List Image Activation Profiles: Response 788 473. Get EC/MCL Description of zBX (Node):
431. Get Image Activation Profile Properties: Response (Part 1) . . . . . . . . . . 901
Request . . . . . . . . . . . . . 790 474. Get EC/MCL Description of zBX (Node):
432. Get Image Activation Profile Properties: Response (Part 2) . . . . . . . . . . 902
Response (Part 1) . . . . . . . . . . 791 475. Activate zBX (Node): Request . . . . . . 904
433. Get Image Activation Profile Properties: 476. Activate zBX (Node): Response . . . . . 904
Response (Part 2) . . . . . . . . . . 792 477. Deactivate zBX (Node): Request . . . . . 906
434. List Load Activation Profiles: Request 798 478. Deactivate zBX (Node): Response . . . . . 907
435. List Load Activation Profiles: Response 798 479. Get zBX (Node) Audit Log: Request . . . . 909
436. Get Load Activation Profile Properties: 480. Get zBX (Node) Audit Log: Response 909
Request . . . . . . . . . . . . . 800 481. Get zBX (Node) Security Log: Request 911
437. Get Load Activation Profile Properties: 482. Get zBX (Node) Security Log: Response 912
Response . . . . . . . . . . . . . 800 483. List zBX (Node) Hardware Messages: Request 914
438. List Group Profiles: Request . . . . . . 805 484. List zBX (Node) Hardware Messages:
439. List Group Profiles: Response . . . . . . 806 Response . . . . . . . . . . . . . 915
440. Get Group Profile Properties: Request 807 485. Get zBX (Node) Hardware Message
441. Get Group Profile Properties: Response 808 Properties: Request . . . . . . . . . 916
442. Energy management as applied throughout 486. Get zBX (Node) Hardware Message
layers of enterprise management . . . . . 817 Properties: Response . . . . . . . . . 917
443. Example of a zBX node group that contains a 487. Delete zBX (Node) Hardware Message:
BladeCenter with blades . . . . . . . . 818 Request . . . . . . . . . . . . . 918
444. Example of a CPC group that contains a 488. Delete zBX (Node) Hardware Message:
zCPC . . . . . . . . . . . . . . 818 Response . . . . . . . . . . . . . 918
445. Example of a CPC (Ensemble) group that 489. zBX object: Sample inventory data . . . . 919
contains a zCPC and a BladeCenter . . . . 819 490. List Top-of-Rack Switches: Request . . . . 923
446. Example of a CPC (Ensemble) group that 491. List Top-of-Rack Switches: Response . . . . 923
contains a zCPC . . . . . . . . . . 819 492. Get Top-of-Rack Switch Properties: Request 925
447. Get Energy Optimization Advice Summary: 493. Get Top-of-Rack Switch Properties: Response 926
Request . . . . . . . . . . . . . 839 494. Get Top-of-Rack Switch Port Details: Request 928
448. Get Energy Optimization Advice Summary: 495. Get Top-of-Rack Switch Port Details:
Response (Part 1) . . . . . . . . . . 840 Response . . . . . . . . . . . . . 928
449. Get Energy Optimization Advice Summary: 496. Update Top-of-Rack Switch Port Properties:
Response (Part 2) . . . . . . . . . . 841 Request . . . . . . . . . . . . . 930

Figures xv
 Level 04a

497. Update Top-of-Rack Switch Port Properties: 540. List Virtualization Hosts of an Ensemble:
Response . . . . . . . . . . . . . 930 Request . . . . . . . . . . . . . 1004
498. Add MAC Filters to Top-of-Rack Switch Port: 541. List Virtualization Hosts of an Ensemble:
Request . . . . . . . . . . . . . 932 Response . . . . . . . . . . . . 1005
499. Add MAC Filters to Top-of-Rack Switch Port: 542. List Virtualization Hosts of a CPC: Request 1007
Response . . . . . . . . . . . . . 932 543. List Virtualization Hosts of a CPC: Response 1008
500. Remove MAC Filters from Top-of-Rack 544. Get Virtualization Host Properties: Request 1009
Switch Port: Request . . . . . . . . . 934 545. Get Virtualization Host Properties: Response
501. Remove Mac Filters from Top-of-Rack Switch for virtualization host of type "prsm" . . . 1010
Port: Response . . . . . . . . . . . 934 546. Get Virtualization Host Properties: Response
502. Add Top-of-Rack Switch Port to Virtual for virtualization host of type "power-vm" . 1011
Networks: Request . . . . . . . . . . 936 547. Get Virtualization Host Properties: Response
503. Add Top-of-Rack Switch Port to Virtual for virtualization host of type "x-hyp" . . . 1012
Networks: Response . . . . . . . . . 936 548. Get Virtualization Host Properties: Response
504. Remove Top-of-Rack Switch Port from the for virtualization host of type "zvm" . . . 1013
Virtual Networks: Request . . . . . . . 938 549. List Virtual Switches: Request. . . . . . 1016
505. Remove Top-of-Rack Switch Port from the 550. List Virtual Switches: Response . . . . . 1016
Virtual Networks: Response. . . . . . . 938 551. Get Virtual Switch Properties: Request 1018
506. List Racks of a zBX: Request . . . . . . 941 552. Get Virtual Switch Properties: Response for
507. List Racks of a zBX: Response . . . . . . 941 virtual switch of type "iedn" . . . . . . 1018
508. Get Rack Properties: Request . . . . . . 942 553. Get Virtual Switch Properties: Response for
509. Get Rack Properties: Response . . . . . . 943 virtual switch of type "qdio" . . . . . . 1019
510. Rack object: Sample inventory data . . . . 943 554. Get Switch Controllers: Request . . . . . 1026
511. List BladeCenters in a Rack: Request 948 555. Get Switch Controllers: Response . . . . 1027
512. List BladeCenters in a Rack: Response 949 556. Virtualization Host object: Sample inventory
513. List BladeCenters in a zBX: Request . . . . 951 data for a virtualization host of type
514. List BladeCenters in a zBX: Response 951 "power-vm" . . . . . . . . . . . . 1035
515. Get BladeCenter Properties: Request . . . . 952 557. Virtualization Host object: Sample inventory
516. Get BladeCenter Properties: Response 953 data for a virtualization host of type "prsm" . 1036
517. Activate BladeCenter: Request . . . . . . 955 558. Virtualization Host object: Sample inventory
518. Activate BladeCenter: Response . . . . . 955 data for a virtualization host of type "x-hyp". 1036
519. Deactivate BladeCenter: Request . . . . . 957 559. List Virtual Servers of a zBX (Node): Request 1064
520. Deactivate BladeCenter: Response. . . . . 958 560. List Virtual Servers of a zBX (Node):
521. BladeCenter object: Sample inventory data 959 Response . . . . . . . . . . . . 1065
522. List Blades in a BladeCenter: Request 966 561. List Virtual Servers of a Node: Request 1067
523. List Blades in a BladeCenter: Response 966 562. List Virtual Servers of a Node: Response 1067
524. List Blades in a zBX: Request . . . . . . 968 563. List Virtual Servers of an Ensemble: Request 1069
525. List Blades in a zBX: Response . . . . . . 969 564. List Virtual Servers of an Ensemble:
526. Get Blade Properties: Request . . . . . . 970 Response . . . . . . . . . . . . 1070
527. Get Blade Properties: Response for blade of 565. List Virtual Servers of a CPC: Request 1072
type "system-x" (similar for type "power") . . 971 566. List Virtual Servers of a CPC: Response 1073
528. Get Blade Properties: Response for blade of 567. List Virtual Servers of a Virtualization Host:
type "dpx150z": . . . . . . . . . . . 972 Request . . . . . . . . . . . . . 1075
529. Get Blade Properties: Response for blade of 568. List Virtual Servers of a Virtualization Host:
type "isaopt": . . . . . . . . . . . 973 Response . . . . . . . . . . . . 1075
530. Activate a Blade: Request . . . . . . . 975 569. Create Virtual Server: Request for a virtual
531. Activate a Blade: Response . . . . . . . 975 server of type "power-vm" . . . . . . . 1080
532. Deactivate a Blade: Request . . . . . . . 977 570. Create Virtual Server: Response for a virtual
533. Deactivate a Blade: Response . . . . . . 977 server of type "power-vm" . . . . . . . 1080
534. Sample inventory data for a blade of type 571. Delete Virtual Server: Request . . . . . 1082
"power" . . . . . . . . . . . . . 982 572. Delete Virtual Server: Response . . . . . 1082
535. Sample inventory data for a blade of type 573. Get Virtual Server Properties: Request 1084
"system-x" . . . . . . . . . . . . 983 574. Get Virtual Server Properties: Response for
536. List Virtualization Hosts of a zBX (Node): virtual servers of "power-vm" (Part 1) . . . 1085
Request . . . . . . . . . . . . . 1000 575. Get Virtual Server Properties: Response for
537. List Virtualization Hosts of a zBX (Node): virtual servers of "power-vm" (part 2) . . . 1086
Response . . . . . . . . . . . . 1000 576. Get Virtual Server Properties: Response for
538. List Virtualization Hosts of a Node: Request 1002 virtual servers of type "prsm" . . . . . . 1087
539. List Virtualization Hosts of a Node: 577. Get Virtual Server Properties: Response for
Response . . . . . . . . . . . . 1002 virtual servers of type "x-hyp" (Part 1) . . . 1088

xvi HMC Web Services API

 Level 04a

578. Get Virtual Server Properties: Response for 617. Virtual Server object: Sample inventory data
virtual servers of type "x-hyp" (Part 2) . . . 1089 for a virtual server of type "power-vm" (Part
579. Get Virtual Server Properties: Response for 2) . . . . . . . . . . . . . . . 1136
virtual servers of type "zvm" . . . . . . 1090 618. Virtual Server object: Sample inventory data
580. Update Virtual Server Properties: Request for a virtual server of type "prsm" . . . . 1137
for a virtual server of type "x-hyp" . . . . 1095 619. Virtual Server object: Sample inventory data
581. Update Virtual Server Properties: Response for a virtual server of type "x-hyp" . . . . 1138
for a virtual server of type "x-hyp" . . . . 1095 620. Object model . . . . . . . . . . . 1140
582. Create Network Adapter: Request for a 621. List Storage Resources: Request . . . . . 1145
virtual server of type "x-hyp" . . . . . . 1097 622. List Storage Resources: Response . . . . 1145
583. Create Network Adapter: Response for a 623. Get Storage Resource Properties: Request 1147
virtual server of type "x-hyp" . . . . . . 1098 624. Get Storage Resource Properties: Response 1147
584. Delete Network Adapter: Request . . . . 1099 625. Create Storage Resource: Request . . . . 1149
585. Delete Network Adapter: Response 1099 626. Create Storage Resource: Response 1149
586. Get Network Adapter Properties: Request 1101 627. Update Storage Resource Properties: Request 1151
587. Get Network Adapter Properties: Response 1101 628. Update Storage Resource Properties:
588. Update Network Adapter: Request for a Response . . . . . . . . . . . . 1151
virtual server of type "x-hyp" . . . . . . 1104 629. Delete Storage Resource: Request . . . . 1152
589. Update Network Adapter: Response for a 630. Delete Storage Resource: Response 1153
virtual server of type "x-hyp" . . . . . . 1104 631. Export World Wide Port Names List: WWPN
590. Reorder Network Adapter: Request 1106 list: Request. . . . . . . . . . . . 1155
591. Reorder Network Adapter: Response 1106 632. Export World Wide Port Names List: WWPN
592. Create Virtual Disk: Request for a virtual list: Response . . . . . . . . . . . 1155
server of type "power-vm" . . . . . . . 1109 633. List Virtualization Host Storage Resources of
593. Create Virtual Disk: Response for a virtual a Storage Resource: Request . . . . . . 1158
server of type "power-vm" . . . . . . . 1109 634. List Virtualization Host Storage Resources of
594. Create Virtual Disk: Request for a virtual a Storage Resource: Response . . . . . . 1159
server of type "x-hyp" . . . . . . . . 1109 635. Storage Resource object: Sample inventory
595. Create Virtual Disk: Response for a virtual data . . . . . . . . . . . . . . 1160
server of type "x-hyp" . . . . . . . . 1110 636. List Virtualization Host HBA Ports: Request 1163
596. Delete Virtual Disk: Request . . . . . . 1111 637. List Virtualization Host HBA Ports:
597. Delete Virtual Disk: Response . . . . . . 1112 Response . . . . . . . . . . . . 1164
598. Get Virtual Disk Properties: Request for a 638. List Virtualization Host Storage Resources:
virtual server of type "power-vm" . . . . 1113 Request . . . . . . . . . . . . . 1167
599. Get Virtual Disk Properties: Response for a 639. List Virtualization Host Storage Resources:
virtual server of type "power-vm" . . . . 1114 Response . . . . . . . . . . . . 1167
600. Get Virtual Disk Properties: Request for a 640. Get Virtualization Host Storage Resource
virtual server of type "x-hyp" . . . . . . 1114 Properties: Request . . . . . . . . . 1169
601. Get Virtual Disk Properties: Response for a 641. Get Virtualization Host Storage Resource
virtual server of type "x-hyp" . . . . . . 1114 Properties: Response for Virtualization Host
602. Update Virtual Disk Properties: Request for a of type "power-vm" or "x-hyp" . . . . . 1170
virtual server of type "x-hyp" . . . . . . 1117 642. Get Virtualization Host Storage Resource
603. Update Virtual Disk Properties: Response for Properties: Response for Virtualization Host
a virtual server of type "x-hyp" . . . . . 1117 of type "zvm" . . . . . . . . . . . 1171
604. Reorder Virtual Disks: Request . . . . . 1119 643. Create Virtualization Host Storage Resource:
605. Reorder Virtual Disks: Response . . . . . 1119 Request . . . . . . . . . . . . . 1174
606. Activate Virtual Server: Request . . . . . 1121 644. Create Virtualization Host Storage Resource:
607. Activate Virtual Server: Response . . . . 1121 Response . . . . . . . . . . . . 1174
608. Deactivate Virtual Server: Request . . . . 1123 645. Delete Virtualization Host Storage Resource:
609. Deactivate Virtual Server: Response 1124 Request . . . . . . . . . . . . . 1176
610. Mount Virtual Media: Request . . . . . 1126 646. Delete Virtualization Host Storage Resource:
611. Mount Virtual Media: Response . . . . . 1126 Response . . . . . . . . . . . . 1176
612. Unmount Virtual Media: Request . . . . 1129 647. Add Virtualization Host Storage Resource
613. Unmount Virtual Media: Response 1130 Paths: Request . . . . . . . . . . . 1179
614. Initiate Virtual Server Dump: Request 1133 648. Add Virtualization Host Storage Resource
615. Initiate Virtual Server Dump: Response 1133 Paths: Response . . . . . . . . . . 1179
616. Virtual Server object: Sample inventory data 649. List Virtual Disks of a Virtualization Host
for a virtual server of type "power-vm" (Part Storage Resource: Request . . . . . . . 1186
1) . . . . . . . . . . . . . . . 1135 650. List Virtual Disks of a Virtualization Host
Storage Resource: Response . . . . . . 1186

Figures xvii
 Level 04a

651. List Virtualization Host Storage Groups: 689. Remove Group of Virtual Servers from a
Request . . . . . . . . . . . . . 1190 Workload Resource Group: Response . . . 1247
652. List Virtualization Host Storage Groups: 690. List Performance Policies: Request . . . . 1258
Response . . . . . . . . . . . . 1190 691. List Performance Policies: Response 1259
653. Get Virtualization Host Storage Group 692. Get Performance Policy Properties: Request 1260
Properties: Request . . . . . . . . . 1192 693. Get Performance Policy Properties: Response
654. Get Virtualization Host Storage Group (Part 1) . . . . . . . . . . . . . 1261
Properties: Response . . . . . . . . . 1192 694. Get Performance Policy Properties: Response
655. List Virtual Networks: Request . . . . . 1202 (Part 2) . . . . . . . . . . . . . 1262
656. List Virtual Networks: Response . . . . . 1202 695. Create Performance Policy: Request 1264
657. Get Virtual Network Properties: Request 1203 696. Create Performance Policy: Response 1264
658. Get Virtual Network Properties: Response 1203 697. Delete Performance Policy: Request 1266
659. Update Virtual Network Properties: Request 1206 698. Delete Performance Policy: Response 1266
660. Update Virtual Network Properties: 699. Update Performance Policy: Request 1268
Response . . . . . . . . . . . . 1206 700. Update Performance Policy: Response 1269
661. Create Virtual Network: Request . . . . . 1208 701. Activate Performance Policy: Request 1270
662. Create Virtual Network: Response . . . . 1208 702. Activate Performance Policy: Response 1270
663. Delete Virtual Network: Request . . . . . 1210 703. Export Performance Policy: Request 1273
664. Delete Virtual Network: Response . . . . 1210 704. Export Performance Policy: Response 1274
665. List Members of a Virtual Network: Request 1212 705. Relationship between reports and the
666. List Members of a Virtual Network: properties used . . . . . . . . . . 1276
Response . . . . . . . . . . . . 1212 706. Generate Workload Resource Groups Report:
667. Virtual Network object: Sample inventory Request . . . . . . . . . . . . . 1280
data . . . . . . . . . . . . . . 1213 707. Generate Workload Resource Group
668. List Workload Resource Groups of an Performance Index Report: Request . . . . 1282
Ensemble: Request . . . . . . . . . 1225 708. Generate Workload Resource Group
669. List Workload Resource Groups of an Resource Adjustments Report: Request. . . 1287
Ensemble: Response . . . . . . . . . 1226 709. Generate Virtual Servers Report: Request 1291
670. Get Workload Resource Group Properties: 710. Generate Virtual Server CPU Utilization
Request . . . . . . . . . . . . . 1227 Report: Request . . . . . . . . . . 1294
671. Get Workload Resource Group Properties: 711. Generate Virtual Server Resource
Response . . . . . . . . . . . . 1228 Adjustments Report: Request . . . . . . 1298
672. Create Workload Resource Group: Request 1230 712. Generate Hypervisor Report: Request 1307
673. Create Workload Resource Group: Response 1231 713. Generate Hypervisor Resource Adjustments
674. Delete Workload Resource Group: Request 1232 Report: Request . . . . . . . . . . 1311
675. Delete Workload Resource Group: Response 1232 714. Generate Service Classes Report: Request 1314
676. Update Workload Resource Group: Request 1234 715. Generate Service Class Resource
677. Update Workload Resource Group: Response 1234 Adjustments Report: Request . . . . . . 1319
678. List Virtual Servers of a Workload Resource 716. Generate Service Class Hops Report:
Group: Request . . . . . . . . . . 1236 Request . . . . . . . . . . . . . 1324
679. List Virtual Servers of a Workload Resource 717. Generate Service Class Virtual Server
Group: Response . . . . . . . . . . 1237 Topology Report: Request . . . . . . . 1332
680. Add Virtual Server to a Workload Resource 718. Generate Load Balancing Report: Request 1334
Group: Request . . . . . . . . . . 1239 719. Relationship between reports and the
681. Add Virtual Server to a Workload Resource properties used . . . . . . . . . . 1361
Group: Response . . . . . . . . . . 1239 720. Generate Workload Resource Groups Report
682. Remove Virtual Server from a Workload (Ensemble Availability Management):
Resource Group: Request . . . . . . . 1241 Request . . . . . . . . . . . . . 1365
683. Remove Virtual Server from a Workload 721. Generate Workload Resource Group
Resource Group: Response . . . . . . . 1241 Availability Status Report: Request . . . . 1370
684. List Groups of Virtual Servers of a Workload 722. Generate Virtual Servers Report: Request 1372
Resource Group: Request . . . . . . . 1243 723. Generate Virtual Servers Report: Request 1375
685. List Groups of Virtual Servers of a Workload 724. Get Performance Management Velocity Level
Resource Group: Response . . . . . . . 1243 Range Mappings: Request . . . . . . . 1377
686. Add Group of Virtual Servers to a Workload 725. Workload Resource Group: Sample
Resource Group: Request . . . . . . . 1245 inventory data (Part 1) . . . . . . . . 1378
687. Add Group of Virtual Servers to a Workload 726. Workload Resource Group: Sample
Resource Group: Response . . . . . . . 1245 inventory data (Part 2) . . . . . . . . 1379
688. Remove Group of Virtual Servers from a 727. Workload Resource Group: Sample
Workload Resource Group: Request. . . . 1247 inventory data (Part 3) . . . . . . . . 1380

xviii HMC Web Services API

 Level 04a

728. Workload Resource Group: Sample 729. Policy XML example, Part 1 . . . . . . 1390
inventory data (Part 4) . . . . . . . . 1381 730. Policy XML example, Part 2 . . . . . . 1391

Figures xix
 Level 04a

xx HMC Web Services API

 Level 04a

Tables
1. Summary of updates for API version 1.1 41. Ensemble power metric group . . . . . . 112
(HMC/SE Version 2.11.1) . . . . . . . . 8 42. Virtual server CPU and memory metric group 112
2. Summary of updates for API version 1.2 43. Virtualization host CPU and memory metric
(HMC/SE Version 2.11.1) . . . . . . . . 8 group . . . . . . . . . . . . . . 114
3. Summary of updates for API version 1.3 44. Workload metrics group - service class data
(HMC/SE Version 2.12.0) . . . . . . . . 9 metric group . . . . . . . . . . . . 115
4. Summary of updates for API version 1.4 45. Virtualization host (vSwitch) uplink metric
(HMC/SE Version 2.12.1) . . . . . . . . 11 group . . . . . . . . . . . . . . 117
5. Summary of updates for API version 1.5 46. Virtualization host (vSwitch) by virtual
(HMC/SE Version 2.12.1) . . . . . . . . 13 network metric group . . . . . . . . . 119
6. Summary of updates for API version 1.6 47. Attached virtual server network adapters
(HMC/SE Version 2.13.0) . . . . . . . . 14 metric group . . . . . . . . . . . . 122
7. Summary of updates for API version 1.7 48. Optimizer IEDN virtual network interface
(HMC/SE Version 2.13.1) . . . . . . . . 16 metric group . . . . . . . . . . . . 124
8. Summary of updates for API version 2.1 49. Optimizer IEDN physical network adapter
(HMC/SE Version 2.13.1) . . . . . . . . 21 metric group . . . . . . . . . . . . 125
9. Summary of updates for API version 2.2 50. Network adapter port metric group . . . . 127
(HMC/SE Version 2.13.1) . . . . . . . . 22 51. Network interface metric group . . . . . 129
10. Summary of updates for API version 2.20 52. Top-of-rack switch port metrics group 131
(HMC/SE Version 2.14.0) . . . . . . . . 23 53. Optimizer IEDN physical network adapter
11. Summary of updates for API version 2.21 metric group . . . . . . . . . . . . 133
(HMC/SE Version 2.14.0) . . . . . . . . 26 54. DPM - Partition: operations summary 139
12. Summary of updates for API version 2.22 55. DPM - Partition: URI variables. . . . . . 140
(HMC/SE Version 2.14.0) . . . . . . . . 26 56. DPM - Adapter: operations summary 140
| 13. Summary of updates for API version 2.23 57. DPM - Adapter: URI variables . . . . . . 141
| (HMC/SE Version 2.14.0) . . . . . . . . 27 58. DPM - Virtual Switch: operations summary 141
| 14. Summary of updates for API version 2.24 59. DPM - Virtual Switch: URI variables . . . . 141
| (HMC/SE Version 2.14.0) . . . . . . . . 30 60. DPM - Capacity Group: operations summary 142
15. Primitive data types. . . . . . . . . . 31 61. DPM - Capacity Group: URI variables 142
16. Compound data types . . . . . . . . . 32 | 62. DPM - Storage Site: operations summary 142
17. Primitive data types in JSON notation . . . 32 | 63. DPM - Storage Site: URI variables. . . . . 142
18. Compound data types in JSON notation 33 | 64. DPM - Storage Fabric: operations summary 142
| 19. error-feature-info object properties . . . . . 44 | 65. DPM - Storage Fabric: URI variables . . . . 143
20. General API services: operations summary 67 | 66. DPM - Storage Switch: operations summary 143
21. General API services: URI variables . . . . 67 | 67. DPM - Storage Switch: URI variables 143
22. topic-info object . . . . . . . . . . . 78 | 68. DPM - Storage Subsystem: operations
23. Inventory service: operations summary 87 | summary . . . . . . . . . . . . . 143
24. Metrics service: operations summary . . . . 87 | 69. DPM - Storage Subsystem: URI variables 144
25. Metrics service: URI variables . . . . . . 87 | 70. DPM - Storage Control Unit: operations
26. BladeCenter temperature and power metric | summary . . . . . . . . . . . . . 144
group . . . . . . . . . . . . . . 103 | 71. DPM - Storage Control Unit: URI variables 145
27. Blade power metric group . . . . . . . 104 | 72. DPM - Storage Group: operations summary 145
28. Channels metric group . . . . . . . . 104 | 73. DPM - Storage Group: URI variables 145
29. CPC overview metric group . . . . . . 105 74. Partition object: base managed object
30. zBX node overview metric group . . . . . 106 properties specializations . . . . . . . 146
31. DPM system overview metric group . . . . 106 75. Partition object: class specific properties 148
32. Logical partitions metric group . . . . . 107 | 76. partition-feature-info object properties 159
33. Partitions metric group . . . . . . . . 108 77. crypto-configuration nested object properties 160
34. zCPC environmentals and power metric 78. crypto-domain-configuration nested object
group . . . . . . . . . . . . . . 108 properties . . . . . . . . . . . . . 160
35. zCPC processors metric group . . . . . . 109 79. Partition object - Virtual Function element
36. Blade CPU and memory metric group 110 properties . . . . . . . . . . . . . 161
37. Crypto metric group . . . . . . . . . 110 80. Partition object - NIC element object
38. Adapters metric group . . . . . . . . 110 properties . . . . . . . . . . . . . 161
39. Flash memory adapters metric group 111 81. Partition object - HBA element object
40. RoCE adapters metric group . . . . . . 111 properties . . . . . . . . . . . . . 163

© Copyright IBM Corp. 2017, 2018 xxi

 Level 04a

82. Create Partition: HTTP status and reason 116. Adapter object: base managed object
codes . . . . . . . . . . . . . . 174 properties specializations . . . . . . . 262
83. Delete Partition: HTTP status and reason 117. Adapter object: class-specific properties 263
codes . . . . . . . . . . . . . . 176 118. Network Port element object properties 271
84. Delete Partition Asynchronously: HTTP status 119. Storage Port element object properties 271
and reason codes . . . . . . . . . . 178 120. List Adapters of a CPC: HTTP status and
85. Delete Partition Asynchronously: Job status reason codes . . . . . . . . . . . . 274
and reason codes . . . . . . . . . . 179 121. Update Adapter Properties: HTTP status and
86. Update Partition Properties: HTTP status and reason codes . . . . . . . . . . . . 278
reason codes . . . . . . . . . . . . 184 122. Change Crypto Type: HTTP status and reason
87. Update Partition Properties Asynchronously: codes . . . . . . . . . . . . . . 281
HTTP status and reason codes . . . . . . 188 123. Create Hipersocket: HTTP status and reason
88. Update Partition Properties Asynchronously: codes . . . . . . . . . . . . . . 283
Job status and reason codes . . . . . . . 188 124. Delete Hipersocket: HTTP status and reason
89. Start Partition: Job status and reason codes 192 codes . . . . . . . . . . . . . . 284
90. Stop Partition: Job status and reason codes 195 125. Get Partitions Assigned to Adapter: HTTP
91. Dump Partition: HTTP status and reason status and reason codes . . . . . . . . 287
codes . . . . . . . . . . . . . . 197 126. Get Network Port Properties: HTTP status
92. Dump Partition: Job status and reason codes 198 and reason codes . . . . . . . . . . 288
| 93. Start Dump Program: Job status and reason 127. Update Network Port Properties: HTTP status
| codes . . . . . . . . . . . . . . 202 and reason codes . . . . . . . . . . 290
94. Perform PSW Restart: Job status and reason 128. Get Storage Port Properties: HTTP status and
codes . . . . . . . . . . . . . . 205 reason codes . . . . . . . . . . . . 292
95. Create Virtual Function: HTTP status and 129. Update Storage Port Properties: HTTP status
reason codes . . . . . . . . . . . . 207 and reason codes . . . . . . . . . . 293
96. Delete Virtual Function: HTTP status and | 130. Change Adapter Type: HTTP status and
reason codes . . . . . . . . . . . . 209 | reason codes . . . . . . . . . . . . 295
97. Get Virtual Function Properties: HTTP status 131. Virtual Switch object: base managed object
and reason codes . . . . . . . . . . 210 properties specializations . . . . . . . 298
98. Update Virtual Function Properties: HTTP 132. Virtual Switch object: class specific properties 298
status and reason codes . . . . . . . . 212 133. Update Virtual Switch Properties: HTTP
99. Create NIC: HTTP status and reason codes 215 status and reason codes . . . . . . . . 305
100. Delete NIC: HTTP status and reason codes 218 134. Capacity Group element object properties 307
101. Get NIC Properties: HTTP status and reason 135. Create Capacity Group: HTTP status and
codes . . . . . . . . . . . . . . 219 reason codes . . . . . . . . . . . . 312
102. Update NIC Properties: HTTP status and 136. Delete Capacity Group: HTTP status and
reason codes . . . . . . . . . . . . 222 reason codes . . . . . . . . . . . . 314
103. Increase Crypto Configuration: HTTP status 137. Get Capacity Group Properties: HTTP status
and reason codes . . . . . . . . . . 224 and reason codes . . . . . . . . . . 316
104. Change Crypto Domain Configuration: HTTP 138. Add Partition to Capacity Group: HTTP
status and reason codes . . . . . . . . 227 status and reason codes . . . . . . . . 318
105. Decrease Crypto Configuration: HTTP status 139. Remove Partition from Capacity Group:
and reason codes . . . . . . . . . . 229 HTTP status and reason codes . . . . . . 320
106. Mount ISO Image: HTTP status and reason 140. Update Capacity Group Properties: HTTP
codes . . . . . . . . . . . . . . 232 status and reason codes . . . . . . . . 322
107. Unmount ISO Image: HTTP status and reason | 141. Storage Site object properties . . . . . . 323
codes . . . . . . . . . . . . . . 233 | 142. Storage Site object: class specific properties 324
| 108. Attach Storage Group to Partition: HTTP | 143. List Storage Sites: HTTP status and reason
| status and reason codes . . . . . . . . 235 | codes . . . . . . . . . . . . . . 326
| 109. Detach Storage Group from Partition: HTTP | 144. Create Storage Site: HTTP status and reason
| status and reason codes . . . . . . . . 238 | codes . . . . . . . . . . . . . . 328
110. Create HBA: HTTP status and reason codes 240 | 145. Delete Storage Site: HTTP status and reason
111. Delete HBA: HTTP status and reason codes 242 | codes . . . . . . . . . . . . . . 330
112. Update HBA Properties: HTTP status and | 146. Get Storage Site Properties: HTTP status and
reason codes . . . . . . . . . . . . 244 | reason codes . . . . . . . . . . . . 332
113. Get HBA Properties: HTTP status and reason | 147. Update Storage Site Properties: HTTP status
codes . . . . . . . . . . . . . . 246 | and reason codes . . . . . . . . . . 334
114. Reassign Storage Adapter Port: HTTP status | 148. Storage Fabric object properties . . . . . 336
and reason codes . . . . . . . . . . 248 | 149. Storage Fabric object: class specific properties 337
115. Open OS Message Channel: HTTP status and | 150. List Storage Fabrics: HTTP status and reason
reason codes . . . . . . . . . . . . 252 | codes . . . . . . . . . . . . . . 338

xxii HMC Web Services API

 Level 04a

| 151. Create Storage Fabric: HTTP status and | 182. Undefine Storage Control Unit: HTTP status
| reason codes . . . . . . . . . . . . 340 | and reason codes . . . . . . . . . . 391
| 152. Delete Storage Fabric: HTTP status and | 183. Get Storage Control Unit Properties: HTTP
| reason codes . . . . . . . . . . . . 342 | status and reason codes . . . . . . . . 393
| 153. Get Storage Fabric Properties: HTTP status | 184. Update Storage Control Unit Properties:
| and reason codes . . . . . . . . . . 344 | HTTP status and reason codes . . . . . . 395
| 154. Update Storage Fabric Properties: HTTP | 185. Add Volume Range: HTTP status and reason
| status and reason codes . . . . . . . . 345 | codes . . . . . . . . . . . . . . 397
| 155. Storage Switch object: base managed object | 186. Remove Volume Range: HTTP status and
| properties specializations . . . . . . . 347 | reason codes . . . . . . . . . . . . 399
| 156. Storage Switch object: class specific properties 348 | 187. Create Storage Path: HTTP status and reason
| 157. List Storage Switches of a Storage Site: HTTP | codes . . . . . . . . . . . . . . 401
| status and reason codes . . . . . . . . 350 | 188. Delete Storage Path: HTTP status and reason
| 158. List Storage Switches of a Storage Fabric: | codes . . . . . . . . . . . . . . 403
| HTTP status and reason codes . . . . . . 352 | 189. Get Storage Path Properties: HTTP status and
| 159. Define Storage Switch: HTTP status and | reason codes . . . . . . . . . . . . 405
| reason codes . . . . . . . . . . . . 354 | 190. Update Storage Path Properties: HTTP status
| 160. Undefine Storage Switch: HTTP status and | and reason codes . . . . . . . . . . 407
| reason codes . . . . . . . . . . . . 356 | 191. Storage Group object: base managed object
| 161. Get Storage Switch Properties: HTTP status | properties specializations. . . . . . . . 411
| and reason codes . . . . . . . . . . 358 | 192. Storage Group object: class specific properties 412
| 162. Update Storage Switch Properties: HTTP | 193. Storage Volume element object properties 416
| status and reason codes . . . . . . . . 359 | 194. Virtual Storage Resource element object
| 163. Move Storage Switch to Storage Site: HTTP | properties . . . . . . . . . . . . . 422
| status and reason codes . . . . . . . . 361 | 195. World Wide Port Name Information nested
| 164. Move Storage Switch to Storage Fabric: HTTP | object: WWPN related properties . . . . . 423
| status and reason codes . . . . . . . . 363 | 196. List Storage Groups: HTTP status and reason
| 165. Storage Subsystem object: base managed | codes . . . . . . . . . . . . . . 425
| object properties specializations . . . . . 365 | 197. Create Storage Group: HTTP status and
| 166. Storage Subsystem object: class specific | reason codes . . . . . . . . . . . . 429
| properties . . . . . . . . . . . . . 366 | 198. Delete Storage Group: HTTP status and
| 167. subsystem-connection-endpoint nested object | reason codes . . . . . . . . . . . . 432
| properties . . . . . . . . . . . . . 366 | 199. Get Storage Group Properties: HTTP status
| 168. List Storage Subsystems of a Storage Site: | and reason codes . . . . . . . . . . 434
| HTTP status and reason codes . . . . . . 368 | 200. storage-volume-request-info nested object for
| 169. Define Storage Subsystem: HTTP status and | "create" operations on "fc" storage volumes . 437
| reason codes . . . . . . . . . . . . 370 | 201. storage-volume-request-info nested object for
| 170. Undefine Storage Subsystem: HTTP status | "create" operations on "fcp" storage volumes . 437
| and reason codes . . . . . . . . . . 372 | 202. storage-volume-request-info nested object for
| 171. Get Storage Subsystem Properties: HTTP | "modify" operations on "fc" storage volumes . 438
| status and reason codes . . . . . . . . 373 | 203. storage-volume-request-info nested object for
| 172. Update Storage Subsystem Properties: HTTP | "modify" operations on "fcp" storage volumes 439
| status and reason codes . . . . . . . . 375 | 204. storage-volume-request-info nested object for
| 173. Move Storage Subsystem to Storage Site: | "delete" operations on "fc" or "fcp" storage
| HTTP status and reason codes . . . . . . 377 | volumes . . . . . . . . . . . . . 439
| 174. Add Connection Endpoint: HTTP status and | 205. Modify Storage Group Properties: HTTP
| reason codes . . . . . . . . . . . . 379 | status and reason codes . . . . . . . . 441
| 175. Remove Connection Endpoint: HTTP status | 206. Add Candidate Adapter Ports to an FCP
| and reason codes . . . . . . . . . . 381 | Storage Group: HTTP status and reason codes 445
| 176. Storage Control Unit object: base managed | 207. Remove Candidate Adapter Ports from an
| object properties specializations . . . . . 384 | FCP Storage Group: HTTP status and reason
| 177. Storage Control Unit object: class specific | codes . . . . . . . . . . . . . . 447
| properties . . . . . . . . . . . . . 384 | 208. List Storage Volumes of a Storage Group:
| 178. Storage Control Unit object: volume-range | HTTP status and reason codes . . . . . . 450
| nested object properties . . . . . . . . 385 | 209. Get Storage Volume Properties: HTTP status
| 179. Storage Control Unit object: storage path | and reason codes . . . . . . . . . . 452
| element object properties. . . . . . . . 385 | 210. Fulfill FICON Storage Volume: HTTP status
| 180. List Storage Control Units of a Storage | and reason codes . . . . . . . . . . 455
| Subsystem: HTTP status and reason codes . . 387 | 211. Fulfill FCP Storage Volume: HTTP status and
| 181. Define Storage Control Unit: HTTP status and | reason codes . . . . . . . . . . . . 457
| reason codes . . . . . . . . . . . . 389

Tables xxiii
 Level 04a

| 212. List Virtual Storage Resources of a Storage 250. psw-description object . . . . . . . . 483
| Group: HTTP status and reason codes . . . 460 251. zaware-network object . . . . . . . . 483
| 213. Get Virtual Storage Resource Properties: 252. ssc-network object . . . . . . . . . . 484
| HTTP status and reason codes . . . . . . 462 253. ip-info object. . . . . . . . . . . . 484
| 214. Update Virtual Storage Resource Properties: 254. network-ip-info object. . . . . . . . . 484
| HTTP status and reason codes . . . . . . 464 255. absolute-capping object . . . . . . . . 485
| 215. Get Partitions for a Storage Group: HTTP 256. Console object: base managed object
| status and reason codes . . . . . . . . 466 properties specializations . . . . . . . 485
| 216. Validate LUN Path: HTTP status and reason 257. Console object: class specific additional
| codes . . . . . . . . . . . . . . 468 properties . . . . . . . . . . . . . 486
217. Core Z resources - Console: operations 258. network-info object properties . . . . . . 486
summary . . . . . . . . . . . . . 473 259. detailed-network-info properties . . . . . 487
218. Core Z resources - Console: URI variables 474 260. paired-ip-info properties . . . . . . . . 487
219. Core Z resources - User: operations summary 474 261. ipv4-info properties . . . . . . . . . 487
220. Core Z resources - User: URI variables 475 262. ipv6-info properties . . . . . . . . . 487
221. Core Z resources - User Role: operations 263. machine-info properties . . . . . . . . 487
summary . . . . . . . . . . . . . 475 264. hardware-message object properties . . . . 488
222. Core Z resources - User Role: URI variables 475 265. mobile-app-preferences object properties 488
223. Core Z resources - Task: operations summary 475 266. Reorder User Patterns: HTTP status and
224. Core Z resources - Task: URI variables 475 reason codes . . . . . . . . . . . . 497
225. Core Z resources - User Pattern: operations 267. log-entry-info object properties. . . . . . 499
summary . . . . . . . . . . . . . 476 268. event-details-info object properties . . . . 499
226. Core Z resources - User Pattern: URI 269. event-data-item-info object properties 499
variables . . . . . . . . . . . . . 476 270. List Console Hardware Messages: HTTP
227. Core Z resources - Password Rule: operations status and reason codes . . . . . . . . 507
summary . . . . . . . . . . . . . 476 271. List Unmanaged CPCs: HTTP status and
228. Core Z resources - Password Rule: URI reason codes . . . . . . . . . . . . 511
variables . . . . . . . . . . . . . 476 272. List Unmanaged zBX Nodes: HTTP status
229. Core Z resources - LDAP Server Definition: and reason codes . . . . . . . . . . 513
operations summary . . . . . . . . . 476 273. User object: base managed object properties
230. Core Z resources - LDAP Server Definition: specializations . . . . . . . . . . . 531
URI variables . . . . . . . . . . . 477 274. User object: class specific additional
231. Core Z resources - Group: operations properties . . . . . . . . . . . . . 531
summary . . . . . . . . . . . . . 477 275. List Users: HTTP status and reason codes 536
232. Core Z resources - Groups: URI variables 477 276. Update User Properties: HTTP status and
233. Core Z resources - CPC: operations summary 478 reason codes . . . . . . . . . . . . 541
234. Core Z resources - CPC: URI variables 479 277. Add User Role to User: HTTP status and
235. Core Z resources - Logical partitions: reason codes . . . . . . . . . . . . 543
operations summary . . . . . . . . . 479 278. Remove User Role from User: HTTP status
236. Core Z resources - Logical partitions: URI and reason codes . . . . . . . . . . 545
variables . . . . . . . . . . . . . 480 279. Create User: HTTP status and reason codes 548
237. Core Z resources - Reset activation profile: 280. Delete User: HTTP status and reason codes 550
operations summary . . . . . . . . . 480 281. User Role object: base managed object
238. Core Z resources - Image activation profile: properties specializations . . . . . . . 553
operations summary . . . . . . . . . 480 282. User Role object: class specific additional
239. Core Z resources - Load activation profile: properties . . . . . . . . . . . . . 553
operations summary . . . . . . . . . 480 283. permission-info object properties . . . . . 555
240. Core Z resources - Group profile: operations 284. Update User Role Properties: HTTP status
summary . . . . . . . . . . . . . 481 and reason codes . . . . . . . . . . 561
241. Core Z resources - Activation profile: URI 285. Add Permission to User Role: HTTP status
variables . . . . . . . . . . . . . 481 and reason codes . . . . . . . . . . 564
242. Core Z resources - Capacity record: 286. Remove Permission from User Role: HTTP
operations summary . . . . . . . . . 481 status and reason codes . . . . . . . . 567
243. Core Z resources - Capacity record: URI 287. Create User Role: HTTP status and reason
variables . . . . . . . . . . . . . 481 codes . . . . . . . . . . . . . . 569
244. ec-mcl-description object . . . . . . . . 482 288. Delete User Role: HTTP status and reason
245. action object . . . . . . . . . . . . 482 codes . . . . . . . . . . . . . . 570
246. ec object . . . . . . . . . . . . . 482 289. Task object: properties . . . . . . . . 572
247. mcl object . . . . . . . . . . . . . 482 290. User Pattern object: properties . . . . . . 577
248. stp-config object . . . . . . . . . . 483 291. Update User Pattern Properties: HTTP status
249. stp-node object . . . . . . . . . . . 483 and reason codes . . . . . . . . . . 583

xxiv HMC Web Services API

 Level 04a

292. Create User Pattern: HTTP status and reason 329. Load activation profile: properties . . . . 795
codes . . . . . . . . . . . . . . 585 330. Group profile: properties. . . . . . . . 803
293. Password Rule object: properties . . . . . 589 331. Capacity records: class-specific properties 810
294. character-rule object properties. . . . . . 590 332. caprec-proc-info object . . . . . . . . 811
295. custom-character-set object properties 591 333. caprec-target object . . . . . . . . . 812
296. Update Password Rule Properties: HTTP 334. Energy management: operations summary 821
status and reason codes . . . . . . . . 596 335. Energy management: URI variables . . . . 821
297. Create Password Rule: HTTP status and 336. Get Energy Optimization Advice Summary:
reason codes . . . . . . . . . . . . 598 HTTP status and reason codes . . . . . . 839
298. LDAP Server Definition object: properties 603 337. Get Energy Optimization Advice Details:
299. Create LDAP Server Definition: HTTP status HTTP status and reason codes . . . . . . 847
and reason codes . . . . . . . . . . 612 338. Ensemble composition: operations summary 861
300. Group object: base managed object properties 339. Ensemble composition: URI variables 862
specializations . . . . . . . . . . . 616 340. Ensemble object: base managed object
301. Group object: class specific additional properties specializations . . . . . . . 862
properties . . . . . . . . . . . . . 616 341. Ensemble object: class specific properties 863
302. match-info object properties. . . . . . . 617 342. Ensemble composition: energy management
303. CPC object: base managed object properties related additional properties . . . . . . 864
specializations . . . . . . . . . . . 629 343. Ensemble composition: MAC address prefix
304. CPC object: class specific additional nested object related additional properties . . 864
properties . . . . . . . . . . . . . 630 344. Ensemble composition: node properties 865
305. ipv6-info object properties . . . . . . . 637 345. zBX infrastructure: operations summary 882
306. hardware-message object properties . . . . 637 346. zBX infrastructure: URI variables . . . . . 883
| 307. cpc-feature-info object properties . . . . . 638 347. zBX object: base managed object properties
308. auto-start-entry object base properties 638 specializations . . . . . . . . . . . 884
309. auto-start-entry object type-specific properties 348. zBX object: class specific properties . . . . 885
when type value is "partition" . . . . . . 638 349. zBX object: class specific additional properties
310. auto-start-entry object type-specific properties (for zBX node) . . . . . . . . . . . 885
when type value is "partition-group" . . . 639 350. zBX object: ec-mcl-description nested object
311. CPC object: energy management related properties (for zBX node) . . . . . . . 888
additional properties . . . . . . . . . 639 351. zBX object: action nested object properties
312. Set Auto-Start List: HTTP status and reason (for zBX node) . . . . . . . . . . . 888
codes . . . . . . . . . . . . . . 670 352. zBX object: ec nested object properties (for
313. Get CPC Audit Log: HTTP status and reason zBX node) . . . . . . . . . . . . 888
codes . . . . . . . . . . . . . . 683 353. zBX object:mcl nested object properties (for
314. Get CPC Security Log: HTTP status and zBX node) . . . . . . . . . . . . 888
reason codes . . . . . . . . . . . . 686 354. zBX object: ipv6-info properties (for zBX
315. List CPC Hardware Messages: HTTP status node) . . . . . . . . . . . . . . 889
and reason codes . . . . . . . . . . 689 355. zBX object: hardware-message object
316. Get CPC Hardware Message Properties: properties (for zBX node) . . . . . . . 889
HTTP status and reason codes . . . . . . 690 356. zBX object: energy management related
317. Delete CPC Hardware Message: HTTP status additional properties (for zBX node) . . . . 889
and reason codes . . . . . . . . . . 692 357. Get EC/MCL Description of zBX (Node):
318. Export WWPN List: HTTP status and reason HTTP status and reason codes . . . . . . 900
codes . . . . . . . . . . . . . . 694 358. Activate zBX (Node): HTTP status and reason
| 319. cpc-info nested object . . . . . . . . . 696 codes . . . . . . . . . . . . . . 904
| 320. adapter-mapping-info nested object . . . . 697 359. Activate zBX (Node): Job status and reason
321. Logical Partition object: base managed object codes . . . . . . . . . . . . . . 904
properties specializations . . . . . . . 704 360. Deactivate zBX (Node): HTTP status and
322. Logical Partition object: class specific reason codes . . . . . . . . . . . . 906
additional properties . . . . . . . . . 704 361. Dectivate zBX (Node): Job status and reason
323. central-storage-allocation nested object codes . . . . . . . . . . . . . . 906
properties . . . . . . . . . . . . . 719 362. Get zBX (Node) Audit Log: HTTP status and
324. expanded-storage-allocation nested object reason codes . . . . . . . . . . . . 908
properties . . . . . . . . . . . . . 719 363. Get zBX (Node) Security Log: HTTP status
325. Open OS Message Channel: HTTP status and and reason codes . . . . . . . . . . 911
reason codes . . . . . . . . . . . . 749 364. List zBX (Node) Hardware Messages: HTTP
326. List Managed Virtual Machines of a Logical status and reason codes . . . . . . . . 914
Partition: HTTP status and reason codes . . 759 365. Get zBX (Node) Hardware Message
327. Reset activation profile: properties . . . . 761 Properties: HTTP status and reason codes . . 916
328. Image activation profile: properties . . . . 768

Tables xxv
 Level 04a

366. Delete zBX (Node) Hardware Message: HTTP 403. fullpack-virtual-disk-zvm object properties 1061
status and reason codes . . . . . . . . 918 404. storage-group-based-virtual-disk object
367. zBX Top-of-Rack switches: properties 919 properties . . . . . . . . . . . . 1061
368. zBX Top-of-Rack switches: tor-port-info 405. linked-virtual-disk object properties 1062
nested object properties . . . . . . . . 920 406. Valid values for the access-modes property
369. Rack object: base managed object properties of a virtual disk object . . . . . . . . 1062
specializations . . . . . . . . . . . 939 407. Activate Virtual Server: HTTP status and
370. Rack object: class specific properties . . . . 939 reason codes . . . . . . . . . . . 1121
371. BladeCenter object: base managed object 408. Storage management: ensemble-level storage
properties specializations . . . . . . . 944 operations . . . . . . . . . . . . 1140
372. BladeCenter object: class specific properties 944 409. Storage management: virtualization host
373. BladeCenter object: energy management storage operations . . . . . . . . . 1141
related additional properties . . . . . . 945 410. Storage management: storage group
374. Activate BladeCenter: HTTP status and operations . . . . . . . . . . . . 1141
reason codes . . . . . . . . . . . . 955 411. Storage management: URI variables 1142
375. Activate BladeCenter: Job status and reason 412. Storage Resource object: base managed
codes . . . . . . . . . . . . . . 955 object properties specializations . . . . . 1142
376. Activate BladeCenter: HTTP status and 413. Storage Resource object: class specific
reason codes . . . . . . . . . . . . 957 properties . . . . . . . . . . . . 1143
377. Deactivate BladeCenter: Job status and reason 414. Virtualization Host Storage Resource object
codes . . . . . . . . . . . . . . 957 properties . . . . . . . . . . . . 1160
378. Blade object: base managed object properties 415. Virtualization Host Storage Resource object:
specializations . . . . . . . . . . . 959 path-information-fcp object properties . . . 1161
379. Blade object: class specific properties 960 416. Virtualization Host Storage Resource object:
380. Blade object: energy management related path-information-eckd object properties . . 1162
additional properties . . . . . . . . . 961 417. Virtualization Host Storage Group object
381. Blade object: IEDN interface nested object properties . . . . . . . . . . . . 1187
properties . . . . . . . . . . . . . 963 418. Virtualization Host Storage Group object:
382. Virtualization management - virtualization free-space-information object properties . . 1187
host: operations summary . . . . . . . 985 419. Virtual network management: operations
383. Virtualization management- virtualization summary . . . . . . . . . . . . 1199
host: URI variables. . . . . . . . . . 986 420. Virtual network management: URI variables 1199
384. Virtualization management - virtual server: 421. Virtual Network object: base managed object
operations summary . . . . . . . . . 986 properties specializations . . . . . . . 1200
385. Virtualization management - virtual server: 422. Virtual Network object: class specific
URI variables . . . . . . . . . . . 987 additional properties. . . . . . . . . 1200
386. Virtualization Host object: base managed 423. Workload resource group management:
object properties specializations . . . . . 988 operations summary . . . . . . . . . 1216
387. Virtualization Host object: class-specific 424. Workload management: URI variables 1219
additional properties . . . . . . . . . 989 425. Workload object: base managed object
388. iedn-virtual-switch object properties . . . . 992 properties specializations . . . . . . . 1219
389. real-uplink object properties . . . . . . 994 426. Workload object: class-specific properties 1220
390. qdio-virtual-switch object properties . . . . 995 427. perf-policy-summary-object . . . . . . 1223
391. Virtual Server object: base managed object 428. avail-policy-summary-object . . . . . . 1223
properties specializations . . . . . . . 1037 429. Performance Policy object: class-specific
392. Virtual Server object: class specific additional properties . . . . . . . . . . . . 1252
properties . . . . . . . . . . . . 1040 430. Performance Policy object: Service class
393. Virtual Server object: virtual server nested object properties . . . . . . . . 1254
availability status with reasons nested object 431. Performance Policy object: classification rule
properties . . . . . . . . . . . . 1054 nested object properties . . . . . . . . 1255
394. Virtual Server object: virtual server 432. Performance Policy object: filter nested
performance policy nested object . . . . 1055 object properties . . . . . . . . . . 1256
395. Virtual Server object: virtual server 433. Format of a workload-report-entry object 1277
availability policy nested object . . . . . 1055 434. Format of a cpu-utilization-range object 1278
396. mac-prefix object properties . . . . . . 1056 435. Format of a perf-status-data-point object 1278
397. network-adapter-power object properties 1056 436. Format of a service-class-pi-data object 1281
398. network-adapter-x-hyp object properties 1056 437. Format of a pi-data-point object . . . . . 1281
399. network-adapter-zvm object properties 1057 438. Format of a report-hypervisor-details object 1300
400. network-adapter-prsm object properties 1059 439. Format of a PowerVM report-hypervisor-
401. Virtual disk object properties . . . . . . 1060 virtual-servers object. . . . . . . . . 1301
402. fullpack-virtual-disk object properties 1061

xxvi HMC Web Services API

 Level 04a

440. Format of an x Hyp report-hypervisor- 457. Workload Element Group object: Workload
virtual-servers object. . . . . . . . . 1302 element group availability status with
441. Format of a z/VM report-hypervisor-virtual- reasons nested object properties . . . . . 1337
servers object . . . . . . . . . . . 1303 458. Availability Policy object: class-specific
442. Format of a PR/SM report-hypervisor- properties . . . . . . . . . . . . 1349
virtual-servers object. . . . . . . . . 1305 459. Availability Policy object: Workload element
443. Format of an equivalent-workload-service- group override nested object properties . . 1351
class object . . . . . . . . . . . . 1321 460. Format of a workload-report-entry object 1363
444. Format of a hop-entry object . . . . . . 1321 461. Format of nested avail-status-data-point
445. Format of a hops-report-statistics object 1322 object . . . . . . . . . . . . . . 1364
446. Format of a hop-application-env object 1322 462. Format of a policy-activation-record object 1366
447. Format of a hop-application-env-virtual- 463. Format of availability-status-record object 1366
server object . . . . . . . . . . . 1323 464. Format of a parent object . . . . . . . 1369
448. Format of an equivalent-workload-service- 465. Performance policy XML elements 1385
class object . . . . . . . . . . . . 1326 466. Performance policy XML: Elements in a
449. Format of a topo-hop object . . . . . . 1326 ServiceClass element . . . . . . . . 1386
450. Format of a topo-virtual-server-node object 1326 467. Performance policy XML: Elements required
451. Format of an appl-env-vs-response-entry for a Velocity element . . . . . . . . 1386
object . . . . . . . . . . . . . . 1328 468. Performance policy XML: Elements in a
452. Format of an appl-env-vs-utilization-entry Filter element . . . . . . . . . . . 1388
object . . . . . . . . . . . . . . 1329 469. Enum values for a class of managed objects 1393
453. Format of a child-virtual-server-node-link 470. Enum values for the name property of User
object . . . . . . . . . . . . . . 1330 Role objects with a type of "system-defined" 1395
454. Workload object: base managed object 471. Enum values for the name property of Task
properties specializations . . . . . . . 1335 objects . . . . . . . . . . . . . 1397
455. Workload Element Group object:
class-specific properties . . . . . . . . 1335
456. Workload Element Group object: Workload
element group availability status nested
object properties . . . . . . . . . . 1336

Tables xxvii
 Level 04a

xxviii HMC Web Services API

 Level 04a

Safety
Safety notices
Safety notices may be printed throughout this guide. DANGER notices warn you of conditions or
procedures that can result in death or severe personal injury. CAUTION notices warn you of conditions
or procedures that can cause personal injury that is neither lethal nor extremely hazardous. Attention
notices warn you of conditions or procedures that can cause damage to machines, equipment, or
programs.

World trade safety information

Several countries require the safety information contained in product publications to be presented in their
translation. If this requirement applies to your country, a safety information booklet is included in the
publications package shipped with the product. The booklet contains the translated safety information
with references to the US English source. Before using a US English publication to install, operate, or
service this product, you must first become familiar with the related safety information in the Systems
Safety Notices, G229-9054. You should also refer to the booklet any time you do not clearly understand
any safety information in the US English publications.

Laser safety information

All IBM Z® (Z) and IBM LinuxONE™ (LinuxONE) models can use I/O cards such as FICON®, Open
Systems Adapter (OSA), InterSystem Channel-3 (ISC-3), zHyperLink Express, or other I/O features which
are fiber optic based and utilize lasers (short wavelength or long wavelength lasers).

Laser compliance
All lasers are certified in the US to conform to the requirements of DHHS 21 CFR Subchapter J for Class
1 or Class 1M laser products. Outside the US, they are certified to be in compliance with IEC 60825 as a
Class 1 or Class 1M laser product. Consult the label on each part for laser certification numbers and
approval information.

CAUTION: Data processing environments can contain equipment transmitting on system links with
laser modules that operate at greater than Class 1 power levels. For this reason, never look into the
end of an optical fiber cable or open receptacle. (C027)

CAUTION: This product contains a Class 1M laser. Do not view directly with optical instruments.
(C028)

© Copyright IBM Corp. 2017, 2018 xxix

 Level 04a

xxx HMC Web Services API

 Level 04a

About this publication

This publication defines, for reference purposes, the external interface of the Hardware Management
Console (HMC) Web Services Application Programming Interface (Web Services API) for IBM Z and IBM
LinuxONE, HMC version 2.14.0. This document specifies the capabilities, input and output formats, and
behaviors of the Web Services API as viewed by an application external to the HMC that is leveraging
that interface.

Related publications
The following publications provide information which supplements the information found within this
document:
v Capacity On Demand User's Guide, SC28-6985
v Ensemble Workload Resource Group Management Guide, GC27-2629
v Ensemble Planning Guide, GC27-2631
v Processor Resource/Systems Manager Planning Guide, SB10-7169
v z/VM CP Planning and Administration Guide, SC24-6178
v z/VM CP Commands and Utility Reference, SC24-6175
v Dynamic Partition Manager (DPM) Guide, SB10-7170
v 3906 Installation Manual for Physical Planning, GC28-6965
v z13® Installation Manual for Physical Planning, GC28-6938
v zEC12 Installation Manual for Physical Planning, GC28-6914
v zBC12 Installation Manual for Physical Planning, GC28-6923
v z BladeCenter Extension Model 004 Installation Manual for Physical Planning, GC27-2630
v zBX Model 003 Installation Manual for Physical Planning, GC27-2619-01
v zBX Model 002 Installation Manual for Physical Planning, GC27-2611-03

Related HMC and SE console information

Hardware Management Console (HMC) and Support Element (SE) information can be found on the
console help system.

Extending zBX connectivity options to Layer-2

Customer experience with zBX has led IBM® to depart from its original requirement to exclusively
support Layer-3 connectivity between the external data network and the intraensemble data network
(IEDN) top-of-rack (TOR) switches in the zBX. A Redpaper™ is available, illustrating a set of pre-tested
configuration examples in support of both Layer-2 and Layer-3 connectivity. The Redpaper, IBM
zEnterprise BladeCenter Extension: Network Connectivity Options (REDP-5036), includes a description of
limitations and trade-offs when deploying Layer-2 versus Layer-3 connectivity.

The Redpaper can be accessed at the following website: http://www.redbooks.ibm.com/redpieces/

abstracts/redp5036.html?Open.

Revisions
A technical change from the previous edition of this document is indicated by a vertical line (|) to the left
of the change.

For the convenience of application programmers that have used the previous version of this book,
Hardware Management Console Web Services API Version 2.14.0, SC27-2636-03, revision notations have been
added to illustrate the changes made since that document was published.

© Copyright IBM Corp. 2017, 2018 xxxi

 Level 04a

For more information about what has changed since the last publication, see “Summary of API version
updates” on page 7.

Accessibility
Accessible publications for this product are offered in EPUB format and can be downloaded from
Resource Link® at http://www.ibm.com/servers/resourcelink.

If you experience any difficulty with the accessibility of any IBM Z® and IBM LinuxONE information, go
to Resource Link at http://www.ibm.com/servers/resourcelink and click Feedback from the navigation
bar on the left. In the Comments input area, state your question or comment, the publication title and
number, choose General comment as the category and click Submit. You can also send an email to
[email protected] providing the same information.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.

Accessibility features
The following list includes the major accessibility features in IBM Z and IBM LinuxONE documentation,
and on the Hardware Management Console and Support Element console:
v Keyboard-only operation
v Interfaces that are commonly used by screen readers
v Customizable display attributes such as color, contrast, and font size
v Communication of information independent of color
v Interfaces commonly used by screen magnifiers
v Interfaces that are free of flashing lights that could induce seizures due to photo-sensitivity.

Keyboard navigation
This product uses standard Microsoft Windows navigation keys.

Consult assistive technologies

Assistive technology products such as screen readers function with our publications, the Hardware
Management Console, and the Support Element console. Consult the product information for the specific
assistive technology product that is used to access the EPUB format publication or console.

IBM and accessibility

See http://www.ibm.com/able for more information about the commitment that IBM has to accessibility.

How to send your comments

Your feedback is important in helping to provide the most accurate and high-quality information. Send
your comments by using Resource Link at http://www.ibm.com/servers/resourcelink. Click Feedback
on the navigation bar on the left. You can also send an email to [email protected]. Be sure to include
the name of the book, the form number of the book, the version of the book, if applicable, and the
specific location of the text you are commenting on (for example, a page number, table number, or a
heading).

xxxii HMC Web Services API

 Level 04a

Part 1. Web Services API fundamentals

Topics in this part describe the fundamentals of Web Services API.

Topics covered in this part are:

v Chapter 1, “Introduction,” on page 3
v Chapter 2, “Base definitions,” on page 31
v Chapter 3, “Invoking API operations,” on page 35
v Chapter 4, “Asynchronous notification,” on page 47
v Chapter 5, “Data model definitions,” on page 57
| v Chapter 6, “Firmware features,” on page 63

© Copyright IBM Corp. 2017, 2018 1

 Level 04a

2 HMC Web Services API

 Level 04a

Chapter 1. Introduction
This chapter provides an overview of IBM z Unified Resource Manager (zManager) APIs, how to enable
and access them, and considerations for compatibility.

Overview
The IBM z Unified Resource Manager (zManager) is a collection of advanced hardware and virtualization
management functions delivered as Z firmware. The functions of zManager are implemented as a
cooperating set of components hosted on the Hardware Management Console (HMC), the Support
Element (SE), the IBM z BladeCenter Extension (zBX) Model 004, the blades of an IBM zEnterprise®
BladeCenter Extension (zBX) Model 003 or Model 002, and as extensions to z/VM®. It provides a
uniform, integrated and workload-oriented administrative model for the heterogeneous computing
configuration provided by a Z environment. The functions provided by zManager include:
v Hardware inventory, initialization, configuration, monitoring and problem analysis for the components
of a Z CPC, including both the traditional Z computing resources as well as the zBX.
v Firmware installation and update for the HMC, SE, traditional CPC components, zBX infrastructure,
Intra-Ensemble Data Network (IEDN) elements, and zBX blades.
v Operational control and energy management for these hardware elements.
v Configuration of function-specialized workload accelerators available as blade optimizers in the zBX.
v Provisioning, configuration, control and monitoring of virtualized computing systems (virtual servers)
on the firmware-managed IBM blade and z/VM environments.
v Secure management of the IEDN through the provisioning and control of IEDN virtual networks.
v Automatic and workload-oriented performance optimization of the heterogeneous, virtualized
environment.

The HMC serves as the administrative access point for zManager. In that capacity, the HMC provides a
web-based, remote-able graphical user interface (UI) to make the zManager functions available to users.
In addition, it hosts the implementation of zManager Web Service API (Web Services API) that is
described in this document.

The Web Services API is a web-oriented programming interface that makes the underlying zManager
capabilities available for use by higher level management applications, system automation functions, or
custom scripting. The functions that are exposed through the API support several important usage
scenarios in virtualization management, including resource inventory, provisioning, monitoring,
automation and workload-based optimization among others.

Components of the API

The Web Services API consists of two major components. Both components are accessed by client
applications by establishing TCP/IP network connections with the HMC.

Web services interface

The web services interface is a request-and-response oriented programming interface by which client
applications obtain information about the system resources managed by zManager, and by which those
applications can perform provisioning, configuration or control actions on those resources.

As is the case for any web-oriented interface, client applications interact with this interface by means of
the Hypertext Transfer Protocol (HTTP), an application protocol that flows over TCP/IP socket
connections. Client applications request operations by forming and sending text-oriented request
messages as defined by HTTP, and the Web Services API responds with text-oriented HTTP response
messages. The use of HTTP makes the API client-programming-language neutral, and thus accessible to a
© Copyright IBM Corp. 2017, 2018 3
 Level 04a

wide variety of client applications. Client applications can be developed in programming languages such
as Java, or in scripting languages such as Perl or Python that include extensive support for performing
HTTP operations.

The design of the API's mapping to HTTP has been influenced by the Representational State Transfer
(REST) style of interface design. The manageable resources of the system are associated with and
identified by durable URIs, and the basic get, update, create and delete operations on those manageable
resources are mapped directly to the HTTP GET, PUT, POST and DELETE methods. Request and
response data is provided using JavaScript Object Notation (JSON), a simple, open and portable transfer
representation. Mapping the functions of the API to HTTP in this way simplifies client application
development and allows access to the API without the need for extensive client side tooling or libraries
as is often the case in other approaches to web services interface design.

Broadly speaking, the web service interface provides two categories of operations:
v Resource (or object) oriented operations, in which a particular request is targeted at a single
manageable resource instance and typically affects just that single resource instance. The majority of
the API has this orientation, for example providing functions for interacting with the virtual servers,
virtualization hosts, virtual networks and workloads of the system.
v Service oriented operations, in which a particular request operates across many or all manageable
resources of the system. The service-oriented operations are provided to support usage scenarios that
cannot be accomplished efficiently using an object-by-object sequence of individual requests. The
operations provided by the Metrics and Inventory services of the API are examples of service-oriented
operations.

Asynchronous notification facility

The web services interface described above is useful to satisfy many usage scenarios, particularly those in
which the client application's interest in and interaction with zManager is focused on performing a
short-term task. In these kinds of applications (typical of automation or simple provisioning), the client
application forms a request, gets a response, processes the response and then “forgets” about the
zManager resource it interacted with. That is, the application does not attempt to retain (or cache)
information about zManager resources long term and then keep that cache up to date.

However, more sophisticated management applications, including those for discovery, monitoring and
advanced provisioning, are not single-request-and-forget with respect to their interest in zManager.
Rather, such applications have a need to obtain and retain (i.e., cache) information about the inventory,
configuration and status of many zManager resources, and to keep that cached information up to date.

In order to support these more sophisticated applications, the Web Services API provides an
asynchronous notification facility by which zManager can inform interested client applications about
changes to the resources managed by zManager.

The API's asynchronous notification facility is designed around the Java Message Service (JMS), an open,
standard framework and API for sending messages between two or more applications.

Enabling and accessing the API

The Web Services API is provided on an HMC that is running with firmware version 2.11.1 or later. The
API can be used to query, configure and control Central Processing Complexes (CPCs) containing a
Support Element (SE) that is running with firmware version 2.11.1 or higher.

By default, the Web Services API is disabled on the HMC. When disabled, the HMC internal firewall is
configured to prohibit connections to any of the TCP/IP ports used by the API. When in this state,
requests to connect to the API network ports are completely ignored by the HMC without a
connection-refused response.

4 HMC Web Services API

 Level 04a

The Web Services API can be enabled and the scope of access to it configured using the Customize API
Settings task in the HMC UI. The Customize API Settings task allows an installation to enable the API
via an overall enabled/disabled setting. When enabled, the HMC internal firewall is reconfigured to
allow access to the relevant network ports. When the API is enabled with default settings, the HMC
allows connections to the API functions from client applications accessing the HMC from any TCP/IP
address. For additional security, an installation can configure the HMC to permit connections to the API
ports only from selected network addresses or subnets. These addresses or subnets are specified by the
Customize API Settings task as well. If specified, these connection restrictions are enforced by the HMC
internal firewall.

In addition to the overall enablement on/off control and the optional client network address filtering,
access to the API is further secured by the requirement for per-user authorization.

The HMC User Management task defines access and other characteristics of an HMC user. This task
manages a user property (Allow access to Web Services management interfaces) to indicate whether a
particular HMC user is to be permitted to use the API or not. By default, this setting is disabled for an
HMC user profile and thus attempts to establish an API session by that user are rejected. The installation
can use the Customize API Settings or User Management tasks of the HMC to set this property for one
or more HMC users and thus allow those users to access the API.

Once a user is permitted to establish API sessions, its actions within those sessions are subject to the
HMC's access control model, as is described in the section that follows.

Authentication and access control

The HMC provides a built-in access control model in which an HMC user authenticates itself to the HMC
to establish its identity, and then based on that identity is permitted or denied the ability to perform
certain operations as specified by the access control configuration. These operations, and the objects on
which they are permitted, are managed with object and task/action permissions that are grouped into
roles that are assigned to HMC users. Roles are managed and assigned to users with the User
Management task on the HMC.

Use of the Web Services API is subject to the same access control policy as is used for UI operations.

Establishing an API session with the HMC requires the initiating application to provide a valid HMC
logon ID and corresponding password in order to authenticate and establish the identity under which its
requests will be performed. (See “Logon” on page 70 for more information.) The API requires the use of
SSL connections so that these login credentials can be flowed securely. The user credentials are validated
by the HMC in the same way they are validated for a logon to the UI, either via the HMC's built-in user
registry or by use of an LDAP directory server. If the HMC logon ID is configured to require multi-factor
authentication, then an additional authentication token is required.

Once a client application has established an API session, its ability to access various managed object
instances and the operations that can be performed on those instances is regulated based on the identity
associated with the API session and the access control policy configured in the HMC for those managed
object instances. Access control requirements vary based on the class of managed object and the operation
for the managed object. These access control requirements for API actions mirror the requirements for
corresponding tasks in the HMC user interface. Details on the authorization requirements for an
operation are specified in the description of that operation.

Alternate HMC considerations

An ensemble is managed by a pair of HMCs that operate in a primary/alternate configuration rather
than by a single HMC. At any point in time, one HMC of the pair is designated as the primary HMC and
has active management responsibility for the resources of the ensemble. The other HMC is designated as

Chapter 1. Introduction 5
 Level 04a

the alternate HMC, and when in this role acts only as a standby for the primary HMC and mirrors
configuration updates from the primary in case the primary fails, but does not otherwise perform active
management.

The Web Services API can and should be enabled on both the primary and alternate HMCs of the pair.

However, client applications should generally connect only with the primary HMC for API purposes.
Because the alternate HMC is not performing active management, it is unable to perform the
management actions implied by API requests, and thus most API operations are designed to be rejected if
directed to the alternate HMC (with HTTP status code 404, reason code 3). The API operations supported
on the alternate HMC are limited to those that control the alternate HMC function itself. The description
of an operation specifically indicates that it is supported on the alternate HMC if this is the case.

Compatibility
The capabilities of the Web Services API will evolve as additional management functionality is added to
zManager. Over time, this evolution could result in a mixture of HMC and client application versions
coexisting in a customer environment. The principles and guidelines outlined in this section are intended
to maximize the compatibility and interoperability among HMC and client applications in such a mixed
environment.

API versioning
Since the functionality of the Web Services API may evolve over time, each functional level of the API is
identified by a version number. This version number is represented in major.minor form, with the initial
version of the API designated as version 1.1.

The API version offered by an HMC can be determined before API logon by using the Query API Version
operation (GET /api/version). The version number of the API is also provided in the response from the
Logon operation.

Enhancements to the API specification that maintain compatibility with previous versions (see principles
below) are indicated by incrementing the minor portion of the version number. So, for example, the first
set of compatible changes to the API would be designated as version 1.2, following the initial 1.1 version.

Because the minor versions within a major version stream (e.g. the 1.x versions) are considered
compatible, the HMC always offers and behaves according to the latest minor version of the API
specification it supports. That means, for example, the API does not offer any facility by which a client
can request version 1.1 behaviors on an HMC that offers version 1.2 level of functionality.

While reasonable effort will be made to preserve compatibility, it may become necessary to make changes
to zManager (and thus the API) that do not maintain compatibility with the previous version. If this
occurs, the introduction of this new (incompatible) behavior is indicated by incrementing the major part
of the version number, and starting the minor part of the version number again at 1. The first such
version would thus be identified as version 2.1.

Allowable changes within a major version

The following kinds of changes to the API specification are allowable within a major version, and thus
result in changes to the minor but not major parts of the API version number.
v Adding new object classes or new operations on existing object classes.
v Adding new properties to the data model of an existing object class.
v Changing existing properties of an existing object class from read-only or mutable to writable using the
API.
v Adding new URIs and operations related to those URIs.

6 HMC Web Services API

 Level 04a

v Adding new optional query parameters to existing URIs where the behavior in the absence of this
query parameter is unchanged.
v Adding new optional fields into input bodies where the behavior in the absence of these new fields is
unchanged.
v Adding new fields to the response bodies of existing operations.
v Adding additional header or body fields to existing notification messages.
v Adding data for new classes of objects to the results provided by the Inventory service.
v Generating new types of notification messages.
v Generating property change notifications for new properties, or for existing properties that did not
provide those notifications previously.
v Adding new enumeration values to enumeration-type fields returned in response bodies without
removing or changing the meaning of any existing enumeration values.
v Adding new error status and reason codes.
v Adding new metric groups.
v Adding new metric fields to the end of existing metric groups.

Requirements on client applications

In order for a client application to correctly interoperate with an HMC that may be offering a higher
minor version of the API, client applications must be designed and developed following the simple
principle of “ignore what you don't understand” when interpreting responses or messages received from
the HMC. This is necessary because the principles of allowable changes specified in the preceding section
allow new fields to be added to preexisting responses or messages.

More specifically, a client application must:

v Ignore, without error, any field in a response body that is not recognized by the application.
v Ignore, without error, any header or body field in a notification message that is not recognized by the
application.
v Ignore, without error, any notification message of an unrecognized type that may be received by the
application.
v Ignore, without error, any object appearing in the response to an Inventory request that are of a class
not recognized by the application.
v Tolerate receiving a value in a field with an enumeration data type that is an unexpected value. If the
application is attempting to display this field, it might consider mapping the unrecognized
enumeration value to some value indicating “other” or “unknown”.
v Ignore, without error, extra values provided in a row of metric group data that reside beyond the last
field currently expected by the application.

These conditions can arise as a result of API extensions that are considered allowable within a given
major version. Following the “ignore what you don't understand” principle prepares a client application
to tolerate these API additions should they occur.

Summary of API version updates

The following functions were introduced in the respective API version:

Note: For each of the following API version summary tables, when an API extension indicates the
addition of new properties to the data model for a specified object class, such an extension also includes
standard changes to several related operations as well even though, for brevity, these related changes are
not specifically mentioned in the table. In general, an extension to an object's data model will also include

Chapter 1. Introduction 7
 Level 04a

corresponding changes to the inputs to or responses from Get Properties, Update Properties and Create
operations for that object class, as appropriate. In addition, the new properties are included in Inventory
Service data for objects of the specified class.
Table 1. Summary of updates for API version 1.1 (HMC/SE Version 2.11.1)
Description HMC MCL SE MCL
Added reason codes 0, 105 and 108 as possible HTTP status code 409 N48180.278 N48168.275
(Conflict) error conditions reported by the Migrate Virtual Server operation.
Changed the backing-virtualization-host-storage-resource property of the N48180.287 None
Virtual Server data model (in the fullpack-virtual-disk nested object) from a
read-only property to a writable property.
Increased the maximum request body size for the Import Storage Access List N48180.288 N48168.294
operation to 1 MB, and increased the maximum request body size for most
other operations to 64KB.
Added the cores-per-processor property to the Blade object data model N48180.296 None
(read-only).
Added inventory and property-change notification support for the N48180.308 N48168.315
Virtualization Host Storage Resource object.
Added the inventory-error-details field and related inventory-error-info N48180.314 N48168.321
nested object to the inventory-error document returned by the Get Inventory
operation when error condition 5 is encountered.
v Added the properties=common query parameter to the Get Virtual Server N48180.319 N48168.325
Properties operation.
v Added the virtual-server-common category and power-vm-virtual-server-
common, prsm-virtual-server-common, x-hyp-virtual-server-common and
zvm-virtual-server-common classes to the Get Inventory operation.
Changed the resources field in the request body for the Get Inventory N48180.340 None
operation from required to optional.
Corrected the range checking for the load-address field of the Load Logical N48180.360 None
Partition operation so that the operation correctly supports loading from an
alternate subchannel.

Table 2. Summary of updates for API version 1.2 (HMC/SE Version 2.11.1)
Description HMC MCL SE MCL
v Added the Mount Virtual Media Image operation. N48180.361 None
v Increased API version number from 1.1 to 1.2.
Corrected the format of the URI returned by the List Members of Virtual N48180.363 None
Network operation for a zBX TOR port to reflect the correct canonical URI
format for zBX TOR port elements.
Added the power-vm-partition-id property to the Virtual Server object data N48180.363 N48168.378
model for PowerVM® virtual servers (read-only)
Added HTTP status code 409 (Conflict) as a possible error condition for the N48180.376 None
List Virtualization Host Storage Resources and Get Virtualization Host
Storage Resource Properties operations.
Added the feature-list property to the Virtualization Host object data model. N48180.380 N48168.402
This property is provided for virtualization hosts on all CPCs supported by
the Web Services API, but the particular features provided by a given
virtualization host will differ based on the release and MCL level of the CPC.

8 HMC Web Services API

 Level 04a

Table 3. Summary of updates for API version 1.3 (HMC/SE Version 2.12.0)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for H09182.023 H09173.028
HMCs at version 2.12.0, and apply to all CPCs supported by the Web
Services API:
v Increased API version number from 1.2 to 1.3.
v Added the power-saving-state property to the BladeCenter and Blade
objects data models, and added the cpc-power-saving-state and
zcpc-power-saving-state properties to the CPC object data model.
v Added "not-supported" as a possible enumeration value for the
power-save-allowed and power-cap-allowed properties of BladeCenter and
Blade objects, and added "not-supported" as a possible enumeration value
of the cpc-power-save-allowed, cpc-power-cap-allowed,
zcpc-power-save-allowed and zcpc-power-cap-allowed properties of the
CPC object.
v Added the status (read-only), acceptable-status (writable), perf-status
(read-only) and compliant-perf-status (writable) properties to the
Workload Resource Group object data model.
v Added most-severe-perf-status and perf-status-data-points fields, and
related perf-status-data-point nested object to the response from the
Generate Workload Resource Groups Report operation.
v Added the perf-policies property to the Virtual Server object data model,
and also added related virtual server performance policy nested object.
v Added "data-retrieval-error" as a possible enumeration value for the
status-detailed field in the response for the Generate Load Balancing
Report operation.
v Added an optional request body containing an optional force input field
to the Unmount Virtual Media operation.
v Changed the Create Virtual Server operation for a zVM virtual server to
require the password field on input rather than allowing it to be optional.
This change has been made to improve security.
v Added HTTP status code 409 (Conflict) as a possible error response
reported by the following Storage Management operations:
– Import Storage Access List
– Create Virtualization Host Storage Resource
– Delete Virtualization Host Storage Resource
– Add Virtualization Host Storage Resource Paths
– Remove Virtualization Host Storage Resource Paths
– Discover Virtualization Host Storage Resources.

Chapter 1. Introduction 9
 Level 04a

Table 3. Summary of updates for API version 1.3 (HMC/SE Version 2.12.0) (continued)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for H09182.023 H09173.028
HMCs at version 2.12.0, but apply only to CPCs with SE version 2.12.0:
v Added cp-cpu-consumption-percent, ifl-cpu-consumption-percent and
other-cpu-consumption-percent fields to the response from the Generate
Hypervisor Report operation for zVM virtualization hosts. These new
fields are provided for zVM virtualization hosts running at version 6.2 or
greater.
v Added the following in support of IBM zAware partitions. These changes
apply only for partitions of the new "zaware" type:
– Added "zaware" as a possible value of the activation-mode property of
Logical Partition and Image Activation Profile objects.
– Added the zaware-network, network-ip-info and ip-info nested objects
as common nested object definitions used for new properties of Logical
Partition objects.
– Added the zaware-host-name, zaware-master-userid,
zaware-master-pw, zaware-network-info, zaware-gateway-info and
zaware-dns-info properties to the Logical Partition and Image
Activation Profile object data models.
– Added HTTP status 400 reason code 306 as a possible error response
from the Load Logical Partition, PSW Restart, Start Logical Partition,
Stop Logical Partition, and Update Image Activation Profile Properties
operations when these operations are attempted on an IBM zAware
partition.
v Added the Cryptos and Flash Memory Adapters metric groups for CPC
objects. Data entries are provided for a CPC in these metric groups if the
CPC has one or more Cryptos or Flash Memory Adapters installed.
v Added new cp-cpu-time, ifl-cpu-time, zaap-cpu-time, ziip-cpu-time and
icf-cpu-time metrics to the Virtualization Host CPU and Memory metric
group (for zVM virtualization hosts).
Added HTTP status code 409 (Conflict) as a possible error condition for the H09182.062 None
List Virtualization Host Storage Resources and Get Virtualization Host
Storage Resource Properties operations.
Added property change support for the unique-device-id property of the H09182.102 None
Storage Resource object.
Added the feature-list property to the Virtualization Host object data model. H09182.119 H09173.149
This property is provided for virtualization hosts on all CPCs supported by
the Web Services API, but the particular features provided by a given
virtualization host will differ based on the release and MCL level of the CPC.

10 HMC Web Services API

 Level 04a

Table 4. Summary of updates for API version 1.4 (HMC/SE Version 2.12.1)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for H49574.020 H49564.021
HMCs at version 2.12.1 or later, and apply to all CPCs supported by the Web
Services API:
v Increased API version number from 1.3 to 1.4.
v Added the Get Network Adapter Properties operation for Virtual Server
objects.
v Added the List Virtualization Host Storage Resources of a Storage
Resource operation for Storage Resource objects.
v Added the List Virtual Disks of a Virtualization Host Storage Resource
operation for Virtualization Host objects.
v Added API support for absolute capping to the Logical Partition and
Image Activation Profile objects, including the following API extensions:
– Added the absolute-processing-capping, absolute-aap-capping,
absolute-ifl-capping, absolute-ziip-capping and absolute-cf-capping
properties to the data model for Logical Partition objects.
– Added the absolute-general-purpose-capping, absolute-aap-capping,
absolute-ifl-capping, absolute-ziip-capping and absolute-icf-capping
properties to the data model for Image Activation Profile elements of
CPC objects.
v Added the partition-identifier property to the data model for Logical
Partition objects.

The following extensions are provided by the HMC Web Services API for
HMCs at version 2.12.1 or later, but primarily apply only to CPCs with SE
version 2.12.1 or later:

Chapter 1. Introduction 11
 Level 04a

Table 4. Summary of updates for API version 1.4 (HMC/SE Version 2.12.1) (continued)
Description HMC MCL SE MCL
v Added support for management of processor performance for virtual H49574.020 H49564.021
servers on x-hyp virtualization hosts, comprising the following API
extensions:
– Added the cpu-perf-mgmt-enabled-x-hyp property to the data model
for Ensemble objects.
– Added the cpu-shares-supported property to the data model for
Virtualization Host objects.
– Extended the existing cpu-perf-mgmt-enabled, initial-shares,
minimum-shares and maximum-shares properties of Virtual Server
objects to now also be applicable to virtual servers of type x-hyp.
– Added the workload-processor-mgmt-status, workload-processor-
mgmt-status-reason, initial-shares, shares, min-shares, and max-shares
fields to the response for the Generate Hypervisor Report operation of
Ensemble objects. when issued for x-hyp virtualization hosts. These
fields were previously provided for PowerVM and/or z/VM
virtualization hosts but not for x-hyp virtualization hosts
v Added support for ensemble availability management, comprising the
following API extensions:
– Added the workload-element-groups, active-avail-policy,
default-avail-policy, custom-avail-policies, avail-status, and
compliant-avail-status properties and related nested objects to the data
model for Workload Resource Group objects.
– Added the Availability Policy element of a Workload Resource Group
and corresponding operations for elements of this class, including List,
Create, Delete, Get Properties, Update Properties and Activate
operations for Availability Policy elements of Workload Resource Group
objects.
– Added the Workload Element Group object and corresponding
operations on objects of this class, including List, Create, Delete, Get
Properties and Update Properties operations for Workload Element
Group objects.
– Added Add To and Remove From operations for managing the
inclusion of Workload Element Groups within Workload Resource
Group objects.
– Added List, Add To and Remove From operations for managing the
inclusion of Virtual Servers within Workload Element Group objects.
– Added reporting operations for availability management, including the
Generate Workload Resource Groups Report (Ensemble Availability
Management), Generate Workload Resource Group Availability Status
Report, Generate Virtual Server Report (Ensemble Availability
Management), and Generate Availability Status Report operations.
– Added an enumeration value of "workload-element-group" as a
possible value of the inclusion-type field in the response for the List
Virtual Servers of a Workload Resource Group operation, to specify
the additional way in which virtual servers can become members of a
Workload Resource Group.
– Added the avail-status, acceptable-avail-status, avail-policies and
workload-element-group properties and related nested objects to the
data model for Virtual Server objects.
v Added the heat-load, heat-load-forced-air and heat-load-water metrics to
the zCPC Environmentals and Power metric group.
v Added RoCE Adapters and Ensemble Power Metric groups.

12 HMC Web Services API

 Level 04a

Table 5. Summary of updates for API version 1.5 (HMC/SE Version 2.12.1)
Description HMC MCL SE MCL
Added the ability to specify per-virtual-server shutdown timeouts and to H49574.075 H49564.070
perform deactivate actions that either use or override the shutdown timeout
specified in the virtual server or its hosting virtualization host configuration.
This new capability applies to CPCs with SE version 2.12.1 or later that have
the specified MCL installed. This new capability comprises the following
detailed API extensions:
v Increased API version number from 1.4 to 1.5.
v Added the enumeration value "virtual-server-shutdown-timeout-override-
support" as a possible feature identifier included in the feature-list
property of the Virtualization Host object to indicate the availability of this
new capability to virtual servers hosted on a Virtualization Host instance.
v Added the shutdown-timeout-source and shutdown-timeout properties to
the data model of the Virtual Server object to allow a customized default
shutdown timeout to be configured for a particular virtual server.
v Added the shutdown-timeout field as an optional request body field for
the Deactivate Virtual Server operation to allow an individual
deactivation action to be performed using a shutdown timeout that is
different than the timeout configured as a default for the virtual server or
its hosting virtualization host.

Chapter 1. Introduction 13
 Level 04a

Table 6. Summary of updates for API version 1.6 (HMC/SE Version 2.13.0)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for N98841 CPC: N98775
HMCs at version 2.13.0 and apply to all SE versions supported by the Web
Services API: zBX: N98822
v Increased API version number from 1.5 to 1.6.
v Added API support for managing HMC user and role definitions,
comprising the following API extensions:
– Added the User object representing a defined HMC user, and associated
List, Create, Delete, Get Properties, Update Properties, Add User Role,
and Remove User Role operations for User objects.
– Added the User Role object representing a security role for HMC users,
and associated List, Create, Delete, Get Properties, Update Properties,
Add Permission and Remove Permission operations for User Role
objects.
– Added the Task object representing the permission to invoke an HMC
UI task or request an associated API operation and associated List and
Get Properties operations for Task objects.
– Added the User Pattern object representing a pattern string used to
match user IDs during logon and associated List, Create, Delete, Get
Properties and Update Properties operations for User Pattern objects.
– Added the Reorder User Patterns operation for Console objects.
– Added the Password Rule object representing a password format and
expiration policy specification and associated List, Create, Delete, Get
Properties and Update Properties operations for Password Rule objects.
– Added the LDAP Server Definition object representing the configuration
of an LDAP server used for HMC authentication and associated List,
Create, Delete, Get Properties and Update Properties operations for
LDAP Server Definition objects.
– Added the replication-override-possible properties for Group objects.
– Added the enumeration values "user" and "user-role" as possible object
class values for the Inventory Service.
v Added API support for determining the characteristics of the virtual server
network adapter used for GPMP purposes, comprising the following API
extensions:
– Added the gpmp-network-adapter property to the data model for
Virtual Server objects.
– Added the adapter-type property to the network-adapter-power and
network-adapter-x-hyp nested object for Virtual Server objects.
v Added the gpmp-available-version property to the data model for
Virtualization Host objects.
v Added the management-enablement-level property to the data model for
CPC objects.

The following extensions are provided by the HMC Web Services API for
HMCs at version 2.13.0 but primarily apply only to managed system with SE
version 2.13.0 or later:

14 HMC Web Services API

 Level 04a

Table 6. Summary of updates for API version 1.6 (HMC/SE Version 2.13.0) (continued)
Description HMC MCL SE MCL
v Added API support for zBX Model 004 ensemble nodes, comprising the N98841 CPC: N98775
following API extensions:
– Added the type property to the data model for a zBX object to indicate zBX: N98822
whether the zBX is a CPC-attached (zBX Model 002/003) or ensemble
node (zBX Model 004) zBX. As related extensions, also added the type
property to the response for the List zBXs of Ensemble operation and
also added it as an optional filtering query parameter for that operation.
Note that when a zBX object represents a zBX node, the value of its
parent property contains the URI of the Ensemble of which it is a
member rather than the URI of the CPC to which it is attached.
– Added an optional new input format for the Add Node to Ensemble
operation to allow a zBX Model 004 to be specified as the node to be
added to the ensemble.
– Added the enumeration value "zbx" as a possible value for the type
property of a Node element of an Ensemble object.
– Added the max-nodes, max-cpc-nodes and max-zbx-nodes properties to
the data model for an Ensemble object.
– Added many additional properties to the data model for a zBX object
when that object represents a zBX node.
– Added the Get EC/MCL Description, Activate, Deactivate, Set Power
Save, Set Power Capping, List Virtualization Hosts and List Virtual
Servers operations for zBX node objects.
– Added the Activate and Deactivate operations for BladeCenter objects
contained within a zBX node.
– Added the List Virtualization Hosts and List Virtual Servers
operations for Ensemble nodes in general.
– Added the enumeration value "node" as a possible value of the
availability status nested object of a Virtual Server object.
– Added the zBX (Node) Overview metric group as a metric group that
can be requested using the Metric Service.
v Added API support for manipulation of hardware messages, comprising
the following API extensions:
– Added the hardware messages container property and hardware
message nested objects to the data model for zBX node and CPC objects
and to the data model for the HMC Console object.
– Added the List Hardware Messages, Get Hardware Message Properties
and Delete Hardware Message operations for zBX node and CPC
objects and the HMC Console object.
v Added API support for the retrieval of audit and security log information,
comprising the following API extensions:
– Added a notification topic and Log Entry notification messages to
provide for asynchronous push-type delivery of new log entries for the
HMC Console object to interested API clients.
– Added the Get Notification Topics operation for Session objects to
allow API clients a more general way of retrieving the names of
notification topics for an API session.
– Added the Get Audit Log and Get Security Log operations for zBX
node and CPC objects and the HMC Console object.
v Added the smt-usage, thread-0-usage and thread-1-usage metrics in the
zCPC Processors metric group.
v Added the enumeration value "virtio-scsi" as a possible value for the
emulation mode property of a virtual disk element of a Virtual Server
object.

Chapter 1. Introduction 15
 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Service API for P08462.053 P00339.068
HMCs at version 2.13.1 and apply to all SE versions supported by the Web
Services API:
v Increased API version number from 1.6 to 1.7.
v Added the following common request validation reason codes:
– HTTP status 400 with reason code 18
– HTTP status 404 with reason codes 5 and 6
– HTTP status 409 with reason codes 4, 5, 6, and 9
v Added the following data model property qualifiers: (e) for effective
properties, and (p) for pseudo properties.
v Added the effective-properties-apply base managed object property for
objects which contain an effective property (a property marked with the
(e) qualifier in the object's data model).
v Added API support for sending commands to and receiving messages
from the operating system (OS) executing in Logical Partitions and
Partitions, comprising the following API extensions:
– Added the operating system notification topic, on which OS messages
are received.
– Added the operating system message notification message which
contains the text from the OS.
– Added information about any operating system notification topics
associated with the API session to the Get Notification Topics response.
– Added the Open OS Message Channel and Send OS Command
operations for Logical Partition objects.
– Added the Open OS Message Channel and Send OS Command
operations for Partition objects.
v Added minimal API support for Managed Virtual Machine objects, such
that they can be discovered, added to User Roles and removed from User
Roles, comprising the following API extensions:
– Added the List Managed Virtual Machines of a Logical Partition
operation for Logical Partition objects. The URIs returned can be used
to add/remove Managed Virtual Machine objects to/from User Roles.
– No further API support is provided. That is, there are no List, Create,
Delete, Get Properties or Update Properties operations for Managed
Virtual Machine objects, and they are not included in the Inventory
Service.

16 HMC Web Services API

 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL

v Added minimal support for unmanaged CPC objects, such that they can
be listed, added to User Roles and removed from User Roles. Unmanaged
CPCs are those which have been discovered by the HMC but are not
configured to be managed by the HMC. This support comprises the
following API extensions:
– Added the List Unmanaged CPCs operation for the Console object. The
URIs returned can be used to add/remove unmanaged CPC objects
to/from User Roles.
– No further API support is provided. That is, there are no Create, Delete,
Get Properties, or Update Properties operations for unmanaged CPC
objects, and they are not included in the Inventory Service.
– Added HTTP status 409 with reason code 329 on operations that target
a CPC object but do not support an undefined CPC object as their
target.
v Added minimal support for unmanaged zBX node objects, such that they
can be listed, added to User Roles, and removed from User Roles.
Unmanaged zBX nodes are those which have been discovered by the
HMC but are not configured to be managed by the HMC. This support
comprises the following API extensions:
– Added the List Unmanaged zBX operation for the Console object. The
URIs returned can be used to add/remove unmanaged zBX node
objects to/from User Roles.
– No further API support is provided. That is, there are no Create, Delete,
Get Properties, or Update Properties operations for unmanaged zBX
node objects, and they are not included in the Inventory Service.
– Added HTTP status 409 with reason code 244 on operations that target
a zBX node object but do not support an undefined zBX node object as
their target.
v Added API support for absolute capping of Logical Partition processor
usage, comprising the following API extensions:
– Added the effective-capacity, absolute-icf-capping,
effective-absolute-icf-capping, absolute-ifl-capping,
effective-absolute-ifl-capping, absolute-general-purpose-capping,
effective-absolute-general-purpose-capping, absolute-ziip-capping,
effective-absolute-ziip-capping and effective-properties-apply
properties to the data model for Group Profile objects.
– Added HTTP status 409 with reason code 9 on Update Group Profile
Properties.

Chapter 1. Introduction 17
 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL

v Added the storage-total-installed, storage-hardware-system-area,

storage-customer, storage-customer-central, storage-customer-expanded
and storage-customer-available properties to the data model for CPC
objects.
v Changed the data model qualifier from (w) to (wo) for the
zaware-master-pw property of Logical Partition and Image Activation
Profile objects. This is not a behavioral change but rather just a data model
notation change to document the behavior using current documentation
conventions.
v Added the storage-central-allocation and storage-expanded-allocation
properties to the data model for Logical Partition objects.
v Added a limit of 500 Workload Resource Groups per ensemble. An
attempt to exceed that limit on a Create Workload Resource Group
operation results in HTTP status 409 with reason code 66.
v To improve security, the group-profile-capacity property of the Logical
Partition object is no longer directly writable through the API. The (w)
qualifier has been removed from that property in the data model for
Logical Partition objects and it is now a read-only property. The way for
an authorized API client to change a Logical Partition's
group-profile-capacity is to change the capacity and/or effective-capacity
property of the Group Profile with which the Logical Partition is
associated.
v Added the effective-capacity and effective-properties-apply properties to
the data model for Group Profile objects.
v Added HTTP status 409 with reason code 9 to Update Group Profile
Properties.
v New HTTP status 400 with reason code 330 on the Update User Role
Properties operation for User Role objects when the request is to disable
the API user's own user ID.
v New HTTP status 400 with reason code 300 on the Update Image
Activation Profile Properties operation for Image Activation Profile
objects.
v Added new cp-all-processor-usage, ifl-all-processor-usage,
icf-all-processor-usage, and iip-all-processor-usage metrics to the CPC
overview metric group.
v Added new exhaust-temperature-celsius metric to the zCPC
environmentals and power metric group.

18 HMC Web Services API

 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL

v Added several enumeration values for classes of managed objects within

User Role objects, due to new managed object types added to this HMC
version.
v Added several enumeration values for the name property of Task objects,
due to new tasks added to this HMC version.
v Removed enumeration values for the name property of Task objects for
tasks that are not provided in this HMC version.
v Changed the descriptive name of some tasks. Those descriptive names are
not part of the programming API. The enumeration values for the name
property of the corresponding Task objects are part of the programming
API and are not changed.

The following extensions are provided by the HMC Web Services API for
HMCs at version 2.13.1 but primarily apply only to managed systems with
SE version 2.13.1 or later:
v Added API support for z Appliance Container Infrastructure (zACI)
Logical Partitions, comprising the following API extensions, but only for
Logical Partitions of the new "zaci" type:
– Added "zaci" as a possible enumeration value for the activation-mode
property of Logical Partition objects.
– Added the zaci-host-name, zaci-master-userid, zaci-master-pw,
zaci-network-info, zaci-gateway-info and zaci-dns-info properties to
the data models for Logical Partition and Image Activation Profile
objects.
– Added "zaci" as a possible enumeration value for the operating-mode
property of Image Activation Profile objects.
v Added API support for energy optimization advice, comprising the
following API extensions:
– Added the Get Energy Optimization Advice Summary and Get
Energy Optimization Advice Details operations for CPC objects.
– Added the last-energy-advice-time property to the data model for CPC
objects.
v Added API support for absolute capping of logical partition processor
usage through the new absolute-icf-capping, effective-absolute-icf-
capping, absolute-ifl-capping, effective-absolute-ifl-capping,
absolute-general-purpose-capping, effective-absolute-general-purpose-
capping, absolute-ziip-capping, and effective-absolute-ziip-capping
properties of the data model for Group Profile objects.

Chapter 1. Introduction 19
 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL

v Added API support for Dynamic Partition Manager (DPM), comprising

the following API extensions (These extensions are only available if the
Feature on Demand record for DPM has been installed on the Support
Element):
– Added the Partition object, representing a partition of a CPC, into
which an operating system can be loaded and then started,and
corresponding operations on object of this class, including List, Create,
Delete, Get Properties, Update Properties, Start, Stop, Dump, PSW
Restart, Mount ISO and Unmount ISO operations for Partition objects.
– Added the Virtual Function element of a Partition and corresponding
operations for elements of this class, including Create, Delete, Get
Properties and Update Properties operations for Virtual Function
elements of Partition objects.
– Added the NIC element of a Partition and corresponding operations for
elements of this class, including Create, Delete, Get Properties and
Update Properties operations for NIC elements of Partition objects.
– Added the HBA element of a Partition and corresponding operations
for elements of this class, including Create, Delete, Get Properties,
Update Properties and Reassign Storage Adapter Port for HBA elements
of Partition objects.
– Added the Adapter object representing a network or storage adapter,
and corresponding operations on objects of this class, including List,
Get Properties, Update Properties, Change Crypto Type, Create
Hipersocket, Delete Hipersocket and Get Partitions Assigned to Adapter
operations for Adapter objects.
– Added the Network Port element of an Adapter and corresponding
operations for elements of this class, including Get Properties and
Update Properties for Network Port elements of Adapter objects.
– Added the Storage Port element of an Adapter and corresponding
operations for elements of this class, including Get Properties and
Update Properties for Storage Port elements of Adapter objects.
– Added the Virtual Switch object representing a CPC's network adapter
and port, and corresponding operations on objects of this class,
including List, Get Properties, Update Properties and Get Connected
VNICs operations for Virtual Switch objects.
– Added the Capacity Group element of a CPC and corresponding
operations for elements of this class, including List, Create, Delete, Get
Properties, Update Properties, Add Partition and Remove Partition for
Capacity Group elements of CPC objects.

20 HMC Web Services API

 Level 04a

Table 7. Summary of updates for API version 1.7 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL
v (cont'd)
– Added the DPM system overview, Partitions, Adapters metric groups.
– Added the dpm-enabled, is-cpacf-enabled and maximum-hipersockets
properties to the data model for CPC objects.
– Added the ability to update the description property of CPC objects
when the CPC is enabled for DPM.
– Added "dpm" as a possible enumeration value for the iml-mode
property of CPC objects. Note that some preexisting CPC properties are
not applicable when the CPC is enabled for DPM; such properties are
not returned on Get CPC Properties nor are they valid for the Update
CPC Properties operation.
– Added HTTP status 409 reason code 4 for the following operations for
CPC objects, because these operations are not valid when the CPC is
enabled for DPM: Activate CPC, Deactivate CPC, Import Profiles, and
Export Profiles.
– The following related objects are not provided for a CPC enabled for
DPM: Logical Partition, Reset Activation Profile, Image Activation
Profile, Load Activation Profile and Group Profile.
– Added the Start CPC, Stop CPC and Export WWPN List operations for
CPC objects.
– Added API support for a partition auto-start list of a CPC, comprising
the following API extensions:
- Added the auto-start-list property to the data model for CPC objects.
- Added the Set Auto-Start List operation for CPC objects.
– Added the enumeration values "partition" and "adapter" as possible
object class values for the Inventory Service.
– Added the enumeration value "dpm-resources" as a possible object
category value for the Inventory Service.
v Added the zaci-boot-selection property to the data model for Image
Activation Profile objects.

Table 8. Summary of updates for API version 2.1 (HMC/SE Version 2.13.1)
Description HMC MCL SE MCL
Increased API version number from 1.7 to 2.1. Note that the change in the P08462.250 P00339.291
major portion of the version number indicates that this version is not
compatible with the previous version. The only incompatible changes in this
version are due to renaming z Appliance Container Infrastructure to IBM
Secure Service Container. Specifically:
v The renaming of the zaci-host-name, zaci-master-userid, zaci-master-pw,
zaci-network-info, and zaci-gateway-info Logical Partition object
properties to ssc-host-name, ssc-master-userid, ssc-master-pw,
ssc-network-info, and ssc-gateway-info, respectively.
v The change of the "zaci" enum value for the Logical Partition
object's activation-mode property to "ssc".
v The renaming of the zaci-host-name, zaci-master-userid, zaci-master-pw,
zaci-network-info, zaci-gateway-info and zaci-boot-selection Image
Activation Profile object properties to ssc-host-name, ssc-master-userid,
ssc-master-pw, ssc-network-info, ssc-gateway-info, and ssc-boot-selection,
respectively.
v The change of the "zaci" enum value for the Image Activation Profile
object's operating-mode property to "ssc".

Chapter 1. Introduction 21
 Level 04a

Table 8. Summary of updates for API version 2.1 (HMC/SE Version 2.13.1) (continued)
Description HMC MCL SE MCL
Removed the restriction that the is-cpacf-enabled property of the CPC object P08462.232
is only present when dpm-enabled is true. The is-cpacf-enabled property is
now always present. Also corrected the qualifier column for is-cpacf-enabled
to indicate that it does not provide property change notifications.

Table 9. Summary of updates for API version 2.2 (HMC/SE Version 2.13.1)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for P08462.261 P00339.304
HMCs at version 2.13.1 and apply to all SE versions supported by the Web
Services API:
v Increased API version number from 2.1 to 2.2.
v Added the String/Hostname data type.
v Provided a more granular value for the sysplex-name property of the
Logical Partition to differentiate when the z/OS logical partition is not in a
sysplex.

The following extensions are provided by the HMC Web Services API for
HMCs at version 2.13.1 but primarily apply only to managed systems with
SE version 2.13.1 or later:
v Added API support for Secure Service Container (SSC) partitions of
DPM-enabled CPCs, comprising the following API extensions:
– Added the type, ssc-host-name, ssc-boot-selection, ssc-ipv4-gateway,
ssc-dns-servers, ssc-master-userid and ssc-master-pw properties to the
data model for Partition objects.
– Added the type property to the response for the List Partitions of a
CPC operation and also added it as an optional filtering query
parameter for that operation.
– Added the ssc-management-nic, ssc-ip-address-type, ssc-ip-address,
ssc-mask-prefix, vlan-id and mac-address properties to the data model
for NIC objects.
– Added HTTP status 400 with reason codes 15, 18 and 20 to the Create
Partition operation.
– Added HTTP status 400 with reason codes 15 and 18 to the Update
Partition Properties operation.
– Added HTTP status 409 with reason code 120 to the job status for the
Start Partition operation.
– Added HTTP status 400 with reason code 15 and HTTP status 409 with
reason code 8 to the Create NIC operation.
– Added HTTP status 400 with reason code 15 to the Update NIC
Properties operation.

22 HMC Web Services API

 Level 04a

Table 10. Summary of updates for API version 2.20 (HMC/SE Version 2.14.0)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for P42675.054 P42601.066
HMCs at version 2.14.0 and apply to all SE versions supported by the Web
Services API:
v Increased API version number from 2.2 to 2.20.
v Added the following common request validation reason codes:
– HTTP status 400 with reason codes 19 and 20
– HTTP status 409 with reason code 11
v Added API support for the HMC mobile app, comprising the following
API extensions:
– Added the mobile-app-preferences property to the Console object data
model.
– Added the Get Mobile App Preferences and Set Mobile App
Preferences operations for the Console object to manage the
console-wide mobile app settings.
– Added the Get CPC Notification Preferences for Device and Update
CPC Notification Preferences for Device operations for the Console
object to manage the mobile app notification preferences for a CPC to a
mobile device.
– Added the client-tag field to the request body for the Logon operation.
v Added API support to manage and interact with the console's multi-factor
authentication support, comprising the following API extensions:
– Added the multi-factor-authentication-required and
force-shared-secret-key-change properties to the User object data
model.
– Added the multi-factor-authentication-required field to the request
body for the Create User operation.
– Added the multi-factor-authentication-code field to the request body
for the Logon operation.
– Added the shared-secret-key and session-credential fields to the
response for the Logon operation.
– New HTTP status 201 on the Logon operation.
– New HTTP status 400 with reason codes 46, 47, 48 and 49 on the Logon
operation.
– Added the Establish Shared Secret Key operation.
– Added the hmc-time field to the response for the Query API Version
operation.
– Expanded the authentication options when connecting to the API
message broker; the session ID and session-specific credential are
required for multi-factor authentication users.
v Relaxed the definition of a pseudo property to no longer require a pseudo
property to also be a container property.
v Added the (c) data model qualifier to the connected-vnic-uris pseudo
property of Virtual Switch objects to denote that it is a container property.
Since psuedo properties were also container properties in previous
versions of the API, this is a documentation-only change and not a
behavioral change.

Chapter 1. Introduction 23
 Level 04a

Table 10. Summary of updates for API version 2.20 (HMC/SE Version 2.14.0) (continued)
Description HMC MCL SE MCL
v Added API enhancements that allow quicker responses when fetching the P42675.054 P42601.066
properties of certain object types, comprising the following API extensions:
– Added a properties query parameter to the following operations to
allow an API client to avoid the overhead involved with fetching object
properties in which it has no interest: Get CPC Properties, Get Logical
Partition Properties.
– Added a cached-acceptable query parameter to the following
operations to allow an API client to indicate that cached (but potentially
out-of-date) property values are acceptable: Get CPC Properties, Get
Logical Partition Properties, Get Reset Activation Profile Properties,
Get Image Activation Profile Properties, and Get Load Activation
Profile Properties.
v Added the Delete Partition Asynchronously and Update Partition
Properties Asynchronously operations for Partition objects.
v Added the fid property to the data model for Virtual Function elements of
Partition objects.
v Made the mac-address property of NIC elements of Partition objects
writable in certain cases.
v Added the vlan-type property to the data model for NIC elements of
Partition objects.
v Relaxed the authorization requirements for access to Load Activation
Profile objects via the List Load Activation Profiles and Get Load
Activation Profile Properties operations to allow access without requiring
CPC object-access permission under certain circumstances. This is
consistent with existing HMC UI behavior.
v Relaxed the authorization requirements for access to Image Activation
Profile objects via the List Image Activation Profiles and Get Image
Activation Profile Properties operations to allow access without requiring
CPC object-access permission under certain circumstances. This is
consistent with existing HMC UI behavior.
v Added synchronous interfaces for retrieving operating system messages,
comprising the following API extensions:
– Added the List OS Messages of a Partition operation for Partition
objects.
– Added the List OS Messages of a Logical Partition operation for
Logical Partition objects.
v Added the sequence-number field to the os-message-info object in
operating system message notifications.
v Added support for more efficient access to certain Partition and Logical
Partition information, comprising the following API extensions:
– Added the List Permitted Partitions operation.
– Added the List Permitted Logical Partitions operation.
v Added the has-unacceptable-status, dpm-enabled and se-version
properties to the response for the List CPC Objects operation.
v Added the classification-text field to the response for the Query API
Version operation.
v Added the last-used-iocds property to the CPC object data model.
v Added the last-used-load-address and last-used-load-parameter properties
to the Logical Partition object data model.
v Relaxed the requirements on the boot-iso-image-name property of
Partition objects and documented the requirements in the Partition object
data model. This affects the Mount ISO Image operation for Partition
objects.
v Corrected the documentation for the Create Partition operation; several
fields were missing from the request body definition.

24 HMC Web Services API

 Level 04a

Table 10. Summary of updates for API version 2.20 (HMC/SE Version 2.14.0) (continued)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for P42675.054 P42601.066
HMCs at version 2.14.0 but primarily apply only to managed systems with
SE version 2.14.0 or later:
v Added support for IBM Virtual Flash Memory, comprising the following
API extensions:
– Added the storage-vfm-increment-size and storage-vfm-total properties
to the CPC object data model.
– Added the initial-vfm-storage, maximum-vfm-storage and
current-vfm-storage properties to the Logical Partition object data
model.
– Added the initial-vfm-storage and maximum-vfm-storage properties to
the Image Activation Profile object data model.
v Added the port property to the ssc-network nested object definition used
by the Logical Partition and Image Activation Profile data models.
v Extended the set of characters permitted in a load parameter, comprising
the following API extensions:
– Allow the following three additional characters (@, $, #) in the
load-parameter field of the request body for the Load Logical Partition,
SCSI Load, and SCSI Dump operations.
– Allow the following three additional characters (@, $, #) in the
ipl-parameter property in the Image Activation Profile and Load
Activation Profile data models.
v Removed support for controlling whether a Logical Partition entering a
wait state causes termination of a time slice:
– The does-wait-state-end-time-slice property of the CPC object is no
longer directly writable through the API. The (w) qualifier has been
removed from that property in the data model for CPC objects and it is
now a read-only property whose value is always false.
– The end-timeslice-on-wait property of the Reset Activation Profile
object is no longer directly writable through the API. The (w) qualifier
has been removed from that property in the data model for Reset
Activation Profile objects and it is now a read-only property whose
value is always false.
– New HTTP status 400 with reason code 19 on the Update CPC
Properties and Update Reset Activation Profile Properties operations.
v Replaced the "esa390" and "esa390-tpf" logical partition activation modes
with the new "general" activation mode, comprising the following API
changes:
– Added the enumeration value "general" as a possible value for the
activation-mode property of a Logical Partition object.
– Added the enumeration value "general" as a possible value for the
operating-mode property of an Image Activation Profile object.
v Due to the removal of support for dynamic changes to the SSC
configuration, the SSC-related properties of the Logical Partition object are
no longer directly writable through the API. The (w) qualifier has been
removed from those properties in the data model for Logical Partition
objects and they are now read-only properties. The affected properties are
ssc-host-name, ssc-master-userid, ssc-master-pw, ssc-network-info,
ssc-gateway-info and ssc-dns-info.
v Added the ssc-gateway-ipv6-info property to the Image Activation Profile
object data model.
v Added the last-energy-advice-time property to the CPC object data model
(applicable to SE version 2.13.1 or later).

Chapter 1. Introduction 25
 Level 04a

Table 11. Summary of updates for API version 2.21 (HMC/SE Version 2.14.0)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for P42675.062
HMCs at version 2.14.0 and apply to all SE versions supported by the Web
Services API:
v Increased API version number from 2.20 to 2.21.
v Added the following as possible enumeration values for the
detected-card-type property of the Adapter objects: "osa-express-6s-1gb",
"osa-express-6s-10gb", "osa-express-6s-1000base-t", "crypto-express-6s",
"ficon-express-16s", and "ficon-express-16s-plus".
v Added more granular controls over which OS message notifications are
presented to a mobile device, comprising the following API extensions:
– Added the new-os-message-filtered field to the response for the Get
CPC Notification Preferences for Device operation.
– Added the new-os-message-filtered field to the request body for the
Update CPC Notification Preferences for Device operation.

Table 12. Summary of updates for API version 2.22 (HMC/SE Version 2.14.0)
Description HMC MCL SE MCL
The following extensions are provided by the HMC Web Services API for P42675.116
HMCs at version 2.14.0 and apply to all SE versions supported by the Web
Services API:
v Increased API version number from 2.21 to 2.22.
v Added API support for accessing the ASCII console of partitions of
DPM-enabled CPCs via WebSockets, comprising the following API
extension:
– Added the Get ASCII Console WebSocket URI operation for Partition
objects.

26 HMC Web Services API

 Level 04a

| Table 13. Summary of updates for API version 2.23 (HMC/SE Version 2.14.0)
| Description HMC MCL SE MCL
| The following extensions are provided by the HMC Web Services API for P42675.232 P42601.286
| HMCs at version 2.14.0 and apply to all SE versions supported by the Web
| Services API:
| v Increased API version number from 2.22 to 2.23.
| v Added the following common request validation reason codes:
| – HTTP status 409 with reason codes 12 and 13
| v Added support for object-specific firmware features, comprising the
| following API extensions:
| – Added the available-features-list property to the CPC object data
| model.
| – Added the available-features-list property to the Partition object data
| model.
| v Added enumeration values for classes of managed objects within User
| Role objects, due to new managed object types added to this HMC
| version.
| v Added enumeration values for the name property of User Role objects,
| due to new system-defined user roles added to this HMC version.
| v Added enumeration values for the name property of Task objects, due to
| new tasks added to this HMC version.
| v Removed enumeration values for the name property of Task objects for
| tasks that are not provided in this HMC version.
| v Changed the descriptive name of some classes of managed objects. Those
| descriptive names are not part of the programming API. The enumeration
| values for the managed object classes are part of the programming API
| and are not changed.
| v Changed the descriptive name of some tasks. Those descriptive names are
| not part of the programming API. The enumeration values for the name
| property of the corresponding Task objects are part of the programming
| API and are not changed.

| The following extensions are provided by the HMC Web Services API for
| HMCs at version 2.14.0 but primarily apply only to managed systems with
| SE version 2.14.0 or later:
| v Added the Import DPM Configuration operation for CPC objects to aid in
| migrating a DPM configuration from a z13 system to a z14 system.

Chapter 1. Introduction 27
 Level 04a

| Table 13. Summary of updates for API version 2.23 (HMC/SE Version 2.14.0) (continued)
| Description HMC MCL SE MCL
|| v Added support for managing a FICON configuration for DPM-enabled
| CPCs and their Partitions, comprising the following API extensions (The
| majority of these extensions are only available if the dpm-storage-
| management feature is enabled on the CPC or Partition of interest):
| – Added the Storage Site object, representing a single storage site in a
| FICON configuration, and corresponding operations on objects of this
| class, including List, Create, Delete, Get Properties, Update Properties
| for Storage Site objects.
| – Added the Storage Fabric object, representing a single storage fabric in
| a FICON configuration, and corresponding operations on objects of this
| class, including List, Create, Delete, Get Properties, Update Properties
| for Storage Fabric objects.
| – Added the Storage Switch object, representing a single storage switch in
| a FICON configuration, and corresponding operations on objects of this
| class, including List, Define, Undefine, Get Properties, Update
| Properties, Move Storage Switch to Storage Site and Move Storage
| Switch to Storage Fabric for Storage Switch objects.
| – Added the Storage Subsystem object, representing a single storage
| subsystem in a FICON configuration, and corresponding operations on
| objects of this class, including List, Define, Undefine, Get Properties,
| Update Properties, Move Storage Subsystem to Storage Site, Add
| Connection Endpoint and Remove Connection Endpoint for Storage
| Subsystem objects.
| – Added the Storage Control Unit object, representing a single storage
| control unit in a FICON configuration, and corresponding operations on
| objects of this class, including List, Define, Undefine, Get Properties,
| Update Properties, Add Volume Range, Remove Volume Range for
| Storage Control Unit objects.
| – Added the Storage Path element of a Storage Control Unit and
| corresponding operations on elements of this class, including Create,
| Delete, Get Properties and Update Properties for Storage Path elements
| of Storage Control Unit objects.
| – Added the Storage Group object, representing a single storage group in
| a FICON configuration, and corresponding operations on objects of this
| class, including List, Create, Delete, Get Properties, Modify Storage
| Group Properties, Add Candidate Adapter Ports to an FCP Storage
| Group, Remove Candidate Adapter Ports from an FCP Storage Group,
| Get Partitions for a Storage Group and Validate LUN Path for Storage
| Group objects.
| – Added the Storage Volume element of a Storage Group object and
| corresponding operations on elements of this class, including List, Get
| Properties, Fulfill FICON Storage Volume, and Fulfill FCP Storage
| Volume for Storage Volume elements of Storage Group objects.
| – Added the Virtual Storage Resource element of a Storage Group object
| and corresponding operations on elements of this class, including List,
| Get Properties, and Update Properties for Virtual Storage Resource
| elements of Storage Group objects.
| – Added the Start Dump Program, Attach Storage Group to Partition,
| and Detach Storage Group from Partition operations for Partition
| objects.
| – Added the enumeration value "storage-volume" as a possible value for
| the boot-device property in the Partition object data model.
| – Added the boot-storage-volume and boot-load-parameters properties
| to the Partition object data model.

28 HMC Web Services API

 Level 04a

| Table 13. Summary of updates for API version 2.23 (HMC/SE Version 2.14.0) (continued)
| Description HMC MCL SE MCL
|| v (cont'd)
| – New HTTP status 409 with reason codes 119, 120, 121 and 122 on the
| Update Partition Properties operation.
| – New HTTP status 409 with reason code 122 on the Start Partition
| operation.
| – New HTTP status 409 with reason code 12 on the following operations
| when the dpm-storage-management feature is enabled on the targeted
| CPC: Export WWPN List, Dump Partition and Create HBA.
| – Added the enumeration values "fc" and "not-configured" as possible
| values for the type field in the Adapter object data model.
| – Added the connection-endpoint-uri and connection-endpoint-class
| properties to the data model for Storage Port elements of Adapter
| objects.
| – Added the Change Adapter Type operation for Partition objects.
| – Added the enumeration values "storage-site", "storage-fabric",
| "storage-switch", "storage-subsystem", "storage-control-unit", and
| "storage-group" as possible object class values for the Inventory Service.
| v Added support for Container Based Processors, comprising the following
| API extensions:
| – Added new cpb-shared-processor-usage, cpb-dedicated-processor-
| usage, and cpb-all-processor-usage metrics to the CPC overview metric
| group.
| – Added new cpb-processor-usage metric to the Logical partitions metric
| group.
| – Added "cbp" as a possible value for the processor-type metric in the
| zCPC processors metric group.
| – Added the processor-count-cbp and processor-count-pending-cbp
| properties to the CPC object data model.
| – Added the initial-cbp-processing-weight, initial-cbp-processing-
| weight-capped, minimum-cbp-processing-weight, maximum-cbp-
| processing-weight, current-cbp-processing-weight,
| current-cbp-processing-weight-capped, andabsolute-cbp-capping
| properties to the Logical Partition object data model.
| – Added the initial-cbp-processing-weight, initial-cbp-processing-
| weight-capped, minimum-cbp-processing-weight, maximum-cbp-
| processing-weight,absolute-cbp-capping, number-dedicated-cbp-
| processors, number-reserved-dedicated-cbp-processors,
| number-shared-cbp-processors, and number-reserved-shared-cbp-
| processors properties to the Image Activation Profile object data model.
| – Added the absolute-cbp-capping and effective-absolute-cbp-capping
| properties to the Group Profile object data model.
| – Added the enumeration value "cbp" as a possible value for the type
| field in the Capacity Record object data model.
| – Added the enumeration value "cbp" as a possible value for the
| processor-type field in the request body for the Add Temporary
| Capacity and Remove Temporary Capacity operations.
|

Chapter 1. Introduction 29
 Level 04a

| Table 14. Summary of updates for API version 2.24 (HMC/SE Version 2.14.0)
| Description HMC MCL SE MCL
| The following extensions are provided by the HMC Web Services API for P42675.233
| HMCs at version 2.14.0 and apply to all SE versions supported by the Web
| Services API:
| v Increased API version number from 2.23 to 2.24.
| v Added the vendor field to the response for the Query API Version
| operation.
| v Added the maximum-partitions property to the CPC object data model.
|

30 HMC Web Services API

 Level 04a

Chapter 2. Base definitions

This chapter provides basic definitions of data types, representation formats and other fundamental
syntactic elements that apply across the Web Services API.

Data types
The following data types are used in the definition of the management data model, input and output
parameters and notification message formats in the Web Services API.
Table 15. Primitive data types
Data type Description
Boolean A logical truth value: either the value true or the value false.
Byte An integer value in the range -2^7 to (2^7)-1 (the range of a signed 8-bit integer)
Float An IEEE 754 floating point number in the range +/-4.9E-324 to +/-3.4028235E+38. Note
that, although IEEE 754 provides for representations of positive or negative Infinity and
NaN, such values are not used within the API.
Long An integer value in the range -2^63 to (2^63)-1 (the range of a signed 64-bit integer)
Integer An integer value in the range -2^31 to (2^31)-1 (the range of a signed 32-bit integer)
Short An integer value in the range -2^15 to (2^15)-1 (the range of a signed 16-bit integer)
String A sequence of Unicode characters. When the number of characters in the string is bounded,
the length or length range is provided in parenthesis, for example String (16) for a 16
character string, or String (0-256) for a string that may range in length from 0 (empty) to 256
characters.
String Enum A String enumeration, i.e. a String for which the possible values are constrained to be one of
a specified set of choices.
String/URI A String that contains a URI path used to designate object instances or operations within the
API.
String/IPV4 Address A String that contains an Internet Protocol Version 4 address presented in dotted-decimal
notation.

Example: “127.0.0.1”
String/IPV6 Address A string that contains an Internet Protocol Version 6 address presented in
colon-separated-hexadecimal notation. Leading and consecutive groups of zeros may be
omitted in the representation as is conventional for IPV6 addresses presented in this form.

Example: “2001:db8:85a3::8a2e:370:7334”
String/Hostname A string that contains an internet hostname that adheres to the following standard
guidelines similar to those in the Internet Engineering Task Force (IETF) RFC 1123:
v length is 1-255 characters
v valid characters are a-z, A-Z, 0-9, period(.), and hyphen(-)
v must not begin or end with a period
v must not contain consecutive periods
v must not be an IPv4 address in dotted-decimal notation (see the String/IPv4 Address
datatype)
Timestamp A non-negative Long integer quantity where the value represents a date and time expressed
as the number of milliseconds since midnight on January 1, 1970 UTC, or the special value
-1 to indicate special treatment of the timestamp field.

© Copyright IBM Corp. 2017, 2018 31

 Level 04a

Table 16. Compound data types

Data type Description
Array of <T> A ordered sequence of zero or more elements each of data type <T>. An array may be
empty, i.e. have no elements contained within it.
Object A nested data structure providing a set of fields, each field having a name, data type and
value. Object types do not formally have names. However, descriptions of these nested
objects will often assign reference names to allow connections to be made in the
documentation between points of use and definition for a given nested object.

Input and output representation

Except for a few special cases, the operations provided by the Web Services API expect their input and
provide their output using a representation known as JavaScript Object Notation, or JSON for short. The
JSON representation is also used within the bodies of notification messages emitted by the API. Unless
some different representation is specifically mentioned in the description of an operation or message, all
operations and messages should be understood to use JSON notation.

JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange

format that defines a small set of formatting rules for the portable representation of structured data. JSON
can represent four primitive types (strings, numbers, booleans, and the value null) and two structured
types (objects and arrays) that together provide sufficient expressive power to represent the manageable
resource configuration, state, inputs, and outputs that appear in this API.

A JSON string is a sequence of zero or more Unicode characters enclosed in quotes.

A JSON object is an unordered collection of zero or more name/value pairs (sometimes referred to in this
document as fields or properties), where a name is a string and a value is a primitive type (string,
number, boolean, or null), an array, or a nested object. Each name/value pair is represented in the form
"name": value and is separated from the next name/value pair by a comma. The collection of
name/value pairs comprising the object is enclosed by left and right braces e.g. { ... }).

An array is an ordered sequence of zero or more values separated from each other by commas and
enclosed in left and right square brackets e.g. [10,20,30]). The values in the array can be primitive or
structured types, i.e. arrays of objects or arrays of arrays are permitted.

The precise BNF syntax of JSON notation is not provided in this document, but can be found in the IETF
information document RFC 4726, The application/json Media Type for JavaScript Object Notation (JSON), July
2006. This RFC can be found in text format on the World Wide Web at:

http://www.ietf.org/rfc/rfc4627.txt

Representing API data types in JSON

The following tables define the mapping between the API data types and their corresponding
representation in JSON notation.
Table 17. Primitive data types in JSON notation
API data type JSON representation
Boolean A JSON boolean with keywords true and false
Byte, Integer, Long, A JSON number with a sign and integer component, but no fraction or exponent part.
Short

32 HMC Web Services API

 Level 04a

Table 17. Primitive data types in JSON notation (continued)

API data type JSON representation
Float A JSON number, possibly including fraction or exponent parts.

On output, values with a magnitude greater than or equal to 10^-3 and less than 10^7 are
representation in floating-point format with a fraction part but not exponent part (e.g. 1.7,
-32.467). Values with magnitudes outside that range are represented in scientific notation
with both fraction and exponent parts (e.g. -4.23E127).
String, String Enum Represented as a JSON string enclosed in quotes.
Timestamp An unsigned JSON number with integer component, but no fraction or exponent part.

Table 18. Compound data types in JSON notation

Data type Description
Array of <T> A JSON square-bracket-enclosed array with elements represented according to the data type
<T>.
Object A JSON curly-brace-enclosed object, with the fields/properties of the nested object
represented as name/value members of the object. The name of a property/field is used
directly as the name part of the JSON object member, and the value of the field/property is
provided as the value part of the member.

All strings in the JSON representation (object member names, and string values) are encoded in UTF-8.

Chapter 2. Base definitions 33

 Level 04a

34 HMC Web Services API

 Level 04a

Chapter 3. Invoking API operations

The Web Services API provides an extensive set of operations that client applications can invoke to obtain
information about the manageable resources of the system, to change those resources' characteristics, and
to take action on them. Because the API is designed using a web services orientation, these operations are
accessed by means of Hypertext Transport Protocol (HTTP) protocol messages flowing across TCP/IP
network connections.

Most aspects of HTTP protocol usage required to invoke API operations or receive responses apply
universally across all of the operations of the API. Rather than repeat these details in the description of
each and every operation, this common information is instead provided in this chapter. The material in
this chapter should be considered to apply to each and every operation of the API unless the
operation-specific description indicates otherwise. Thus, the information in his chapter should be
consulted in conjunction with the operation-specific descriptions elsewhere in this document when
determining how to invoke a specific API operation.

HTTP protocol standard

The Web Services API has been designed in accordance with the HTTP version 1.1 protocol, as defined in
the W3C internet standards document RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, June 1999. This
RFC can be found in HTML format on the World Wide Web at: http://www.w3.org/Protocols/rfc2616/
rfc2616.html

The API requires that all clients interact using the HTTP/1.1 protocol. The API does not support clients
that use HTTP/1.0.

Note: While the API does not specifically assume or exclude any particular client user agent, its use and
interpretation of HTTP elements has been designed presuming that the client application interacting with
the API is a programmatic web application client or HTTP-capable scripting client rather than a standard
browser-based application.

Connecting to the API HTTP server

When the Web Services API is enabled, the HMC API HTTP server listens for SSL-based socket
connections on TCP port 6794. The HMC is enabled for both the SSL version 3 and TLS version 1
protocols on this SSL port. It does not accept non-SSL connections. The set of cipher suites enabled for the
HMC API HTTP server is controlled by the Certificate Management task on the HMC. Note, the default
set of cipher suites may change with updates to the HMC if one or more of the cipher suites are found to
be weak or vulnerable.

The listening port for the API HTTP server is a fixed port number and is not subject to customer
reconfiguration. Thus, client applications can treat this as a well-known port number rather than
requiring customer input when configuring the networking parameters the client will use to connect to
the HMC.

HTTP header field usage

HTTP request and response messages include elements known as headers fields (often referred to simply
as headers for short) that provide request metadata. Certain headers are required or provided in all HTTP
messages, while others are present in selected messages depending on content.

This section describes the use of header fields by the Web Services API.

© Copyright IBM Corp. 2017, 2018 35

 Level 04a

Required request header fields

The following HTTP request headers are relevant to all request methods (GET, PUT, POST, DELETE) and
are required on all API requests (except as indicated for the Logon and Query API Version operations).

HTTP header name Rqd/Opt Description

Host Required Specifies the Internet host and port number of the HMC to which the request is
being directed, as obtained from the original URI given by the client
application. The Web Services API enforces that this header is provided as
required by the HTTP protocol, but does not check or use the value of the
header in any way.
X-API-Session Required1 An opaque string that provides a cryptographically strong identifier of the API
session (known as a session id) under which this request is executed. This
header is required on all requests that require authentication. The Login
operation begins a new HMC session and includes credentials identifying the
HMC user for the session. Upon successful authentication, the Login operation
returns the value to be used in the X-API-Session header for all subsequent
requests of the same session. Failure to include this header on a request
requiring authentication results in status code 403 (Forbidden) with reason code
4. Specifying an invalid session id results in status code 403 (Forbidden) with
reason code 5.
Note:
1. Not required on requests to the Query API Version and Logon operations since these operations can be
performed before an API session has been established.

For requests made using the HTTP PUT or POST methods, the following additional request headers are
required if a request body is being provided. If an operation being requested via POST method does not
require a request body, these headers can be omitted.

HTTP header name Rqd/Opt Description

Content-Length Required if When used in a request, specifies the length of the request body. If omitted, the
request request is presumed to not contain a body.
body
present The API limits the size of request bodies in order to control usage of memory
resources on the HMC. Unless a different limit is specified for a particular
operation, in general the largest request body accepted by the API is 64KB.
Requests with bodies that exceed this maximum are rejected with an HTTP
status 413 (Request Entity Too Large) response.
Content-Type Required if When used in a request, specifies the MIME media type of the request body
request contained in the request. This header is required if the Content-Length header
body is supplied and specifies a nonzero request body length, otherwise status code
present 400 (Bad Request) will result.

Optional request headers

The following HTTP request headers are relevant to all request methods (GET, PUT, POST, DELETE) and
may be specified on these method requests but are not required. If present, they are interpreted by the
API in the indicated way.

36 HMC Web Services API

 Level 04a

HTTP header name Rqd/Opt Description

Accept Optional Specifies the list of response MIME media types that the client application is
prepared to accept for the response to the request. This header is provides for
content negotiation between the client and the server in cases where the Web
Services API supports multiple possible response media types for a given
operation.

In the current implementation, the Web Services API supports only a single
response media type for each operation. For the majority of operations, that
media type is JSON (application/json), but selected operations support a
different media type (indicated in the descriptions of those special operations).

If this header is omitted, the Web Services API responds using the (single)
media type supported for the operation. If the header is included, it must allow
for the single media type that the operation supports, otherwise the request
will fail with HTTP status code 406 (Not Acceptable).

If an operation is extended to support multiple media types, compatibility will

be maintained for existing clients that request the operation without specifying
an Accept header.
X-Audit-Id Optional A string that provides additional client identity information that is included in
all audit records created for this request, in addition to the API user's HMC
login identity. This header is intended to provide improved audit logging in the
case of clients that make requests on behalf of multiple upstream users while
logged into the API under a single HMC login identity. Such clients should
provide the identity of their upstream user in this header so that the requests
of different upstream users can be distinguished in the HMC audit logs. The
HMC will use up to the first 64 characters of information from this header if
present, and silently ignore the remainder of the header's value if it is longer
than 64 characters.
X-Client-Correlator Optional A string that provides diagnostic information pertaining to this request that is
of significance to the client, such as a client request number or the like. The
HMC will record this information in selected diagnostic trace or log data it
collects so as to allow better cross-correlation of this information with similar
information maintained by the client. This data supplied in this header is
intended to assist in product problem determination and does not otherwise
affect the operation of the API. The HMC will use up to the first 64 characters
of information from this header if present, and silently ignore the remainder of
the header's value if it is longer than 64 characters.

Standard response headers

The following HTTP response headers are always provided in the response to all requests.

HTTP header
name Description
Date The date and time, from the perspective of the HMC's clock, at which the response message was
generated. As required by the HTTP protocol specification, this date is an HTTP full date sent in
the RFC 1123-defined fixed length format.

Example: Sun, 08 Oct 1961 10:08:00 GMT

The following HTTP response headers are provided in the response to all requests except those that result
in a 204 (No Content) HTTP status code.

Chapter 3. Invoking API operations 37

 Level 04a

HTTP header
name Description
Content-Length When used in a response, specifies the length of the response body. If omitted, the response does
not contain a body.
Content-Type When used in a response, specifies the MIME media type of the response body. This response
header is provided any time the Content-Type header is provided and specifies a nonzero length.

Additional response headers

Some operations may return additional response headers beyond those described in “Standard response
headers” on page 37. The following table describes these possible additional response headers.
Operations that return these additional headers indicate that they do so in the operation description.

HTTP header
name Description
Location The URI of the resources that was created by the operation.

This header is provided for operations that complete successfully with an HTTP status code of
201 (Created).
X-API-Session An opaque string that provides a cryptographically strong identifier of the API session that was
created for the client.

This header is provided in the response to a successful Logon operation.

X-Request-Id A string that provides diagnostic information identifying the request from the perspective of the
HMC. This same information is included in the API log entries that are recorded by the HMC for
the request. If captured by the client from a response, a client application developer or support
technician can use this information to locate the HMC API log entry corresponding to a particular
request. The value of this header will be 64 characters or less.

This header is provided in the responses to all requests.

Media types
The following media types are applicable to the use of the Web Services API, and thus may appear in the
values of Accept or Content-Type header fields.

MIME media type Description

application/json JavaScript Object Notation (JSON), as described by RFC
4627. This media type is used by the Web Services API
for both request and response representation for the
majority of the operations in the API. The JSON text is
encoded using the UTF-8 charset.
application/vnd.ibm-z-zmanager-metrics Custom output format used for providing the results to
the Get Metrics operation of the metrics service. The
result text is encoded using the UTF-8 charset.
application/xml Extensible Markup Language, used for the input and
output formats for the Export Performance Policy and
Import Performance Policy operations of the workload
object. The XML text is encoded using the UTF-8 charset.
application/octet-stream Binary data. This media type is used by the Web Services
API for the request representation for the Mount Virtual
Media Image operation of the Virtual Server object.

38 HMC Web Services API

 Level 04a

HTTP status codes

The HMC API provides standard HTTP status codes in the response to requests to indicate the success or
failure of the request. Unless stated otherwise in the description of an operation, the following general
interpretations of the status code values apply.

HTTP status code Description/Causes

200 (OK) The request has succeeded completely. A response body is provided that contains the results of
the request.
201 (Created) The request has succeeded completely and resulted in the creation of a new managed
resource/object. The URI for the newly created managed resource is provided in a Location
header. (POST methods only)
202 (Accepted) The request was successfully validated and has been accepted to be carried out asynchronously.
204 (No Content) The request succeeded completely, and no additional response information is provided.
400 (Bad Request) The request was missing required input, had errors in the provided input, or included
extraneous input. Additional information regarding the error is provided in an error response
body that includes a reason code with additional information.
403 (Forbidden) Multiple error conditions result in this status code:
v The request requires authentication but no X-API-Session header was provided, or one was
provided but the session ID was invalid.
v The user under which the API request was authenticated is not authorized to perform the
requested operation.
v The ensemble is not operating at the management enablement level required to perform this
operation.
404 (Not Found) Multiple error conditions result in this status code:
v The URI does not designate an extant resource, or designates a resource for which the API
user does not have object-access permission.
v The URI designates a resource or operation that is not supported by the HMC because it is
currently the alternate HMC.
405 (Method Not The request specifies an HTTP method that is not valid for the designated URI.
Allowed)
406 (Not The Accept header for the request does not include at least one content representation
Acceptable) supported by the Web Services API.
409 (Conflict) The managed resource is in an incorrect state (status) for performing the requested operation.
Additional information regarding the error is provided in an error response body that includes
a reason code with additional information.
413 (Request The request includes a request body that is too large.
Entity Too Large)
Unless a different limit is specified for a particular operation, in general the largest request
body accepted by the API is 64 KB.
415 (Unsupported The Content-Type header for the request specifies a representation that is not supported by the
Media Type) Web Services API.
500 (Server Error) A server error occurred during processing of the request.
501 (Not The request specifies an HTTP method that is not recognized by the server (for any resource).
Implemented) Note: The response body that accompanies this error is not a JSON response body as defined
in “Error response bodies” on page 40.
503 (Service The request could not be carried out by the HMC due to some temporary condition.
Unavailable)
505 (HTTP Version The request specifies an HTTP protocol version that is not supported by the Web Services API.
Not Supported)

Chapter 3. Invoking API operations 39

 Level 04a

Error response bodies

For most 4xx and 5xx HTTP error status codes, additional diagnostic information beyond the HTTP status
code is provided in the response body for the request. The API client can use the content-type header to
determine the type of information in the response body. If the value of the content-type header is
application/json, the following information is provided in the form of a JSON object containing the
following fields:

Field name Type Description

request-method String The HTTP method (DELETE, GET, POST, PUT) that caused this error response.
request-uri String The URI that caused this error response.
request-query- Array of An array of query-parm-info objects (described in the table below) that identify the
parms query- query parameters specified on the request and their values. Each query-parm-info
parm- object identifies a single query parameter by its name and includes its value(s). If the
info request contains no query parameters, this field is omitted.
objects
request-headers header- A header-info object (described in the table below) that describes the HTTP headers
info specified on the request. If the request contains no HTTP headers, this field is omitted.
object
request- String The name of the HMC user associated with the API session under which the request
authenticated-as was issued. If the request was issued without an established session or there is no
HMC user bound to the session, this field is omitted.
request-body String The request body, in the form of a JSON document. Note that, since it is in the form of
a JSON document, this may not be exactly what was submitted by the API client
program, but it is semantically equivalent. If the request body could not be parsed or
some other error prevented the creation of a JSON document from the request body,
this field is omitted and the request body is instead available in the
request-body-as-string field.
request-body-as- String The complete request body, or some portion of the request body, exactly as it was
string submitted by the API client program. The request-body-as-string-partial field
indicates whether the complete request body is provided. If the request-body field is
present, this field is omitted.
request-body-as- Boolean When the request-body-as-string field is present, this boolean indicates whether the
string-partial request-body-as-string field contains only part of the request body (true) or the entire
request body (false). If the request-body-as-string field is not present, this field is
omitted.
http-status Integer HTTP status code for the request.
reason Integer Numeric reason code providing more details as to the nature of the error) than is
provided by the HTTP status code itself. This reason code is treated as a sub-code of
the HTTP status code and thus must be used in conjunction with the HTTP status
code to determine the error condition. Standard reason codes that apply across the
entire API are described in“Common request validation reason codes” on page 41.
Additional operation-specific reason codes may also be documented in the description
of the specific API operations.
message String Message describing the error. This message is not currently localized.
stack String Internal HMC diagnostic information for the error. This field is supplied only on
selected 5xx HTTP status codes.
error-details Object A nested object that provides additional operation-specific error information. This field
is provided by selected operations, and the format of the nested object is as described
by that operation.

Each query-parm-info object contains the following fields:

40 HMC Web Services API

 Level 04a

Field name Type Description

{query_parm_name} Array of The value of the {query_parm_name} query parameter. If this query parameter was
Strings specified multiple times, there will be multiple entries in this array, one for each
instance of this query parameter.

The header-info object contains the following field(s), one for each header present on the request:

Field name Type Description

{header_name} String The value of the {header_name} HTTP request header. It will be either a single string or
or Array an array of strings.
of
Strings

Usage notes:
v The message provided in the message field is primarily intended as a convenience for use by
developers when developing and testing client applications. Because it is not localized, it may not be
appropriate for client applications to simply pass this message on to their clients when reporting errors
to those upstream clients. Instead, client applications can use the value in the reason field as a key in
obtaining a client-provided message that may be more appropriate to use.
v Because the reason code is treated as a sub-code of the HTTP status code, the same reason code value
is often defined for multiple different HTTP status codes and has a different meaning in each case. For
example, reason code 1 when considered for a 400 (Bad Request) status code has a different meaning
than when considered for a 403 (Forbidden) status code. For this reason, client applications that make
decisions based on the reason codes should always include checking the HTTP status code as part of
the relevant logic (e.g.test for status code == 400 AND reason code == 1, not just reason code == 1
alone).

Common request validation reason codes

The Web Services API performs request validation on each request it receives to ensure the request is
correctly formed and appropriate before it begins processing the request. Many errors of basic request
syntax can occur on all or a large number of the operations provided by the API. Validation for these
kinds of errors is done in a common way across all of the operations and results in a common (not
request-specific) reason code being reported if errors are detected. Other validation is operation-specific
by nature, and results in operation-specific reason codes when errors are detected.

The following table provides the HTTP status codes and reason codes for common request validation.
These status and reason codes may be reported on any of the operations of the API.

Chapter 3. Invoking API operations 41

 Level 04a

Reason
HTTP status code code Description
400 (Bad Request) 1 The request included an unrecognized or unsupported query parameter.
2 A required request header is missing or invalid.
3 A required request body is missing.
4 A request body was specified when not expected.
5 A required request body field is missing.
6 The request body contains an unrecognized field (i.e. one that is not listed as
either required or optional in the specification for the request body format for the
operation).
7 The data type of a field in the request body is not as expected, or its value is not
in the range permitted.
8 The value of a field does not provide a unique value for the corresponding data
model property as required.
9 The request body is not a well-formed JSON document.
10 An unrecognized X-* header field was specified.
11 The length of the supplied request body does not match the value specified in the
Content-Length header.
13 The maximum number of logged in user sessions for this user ID has been
reached; no more are allowed.
14 Query parameters on the request are malformed or specify a value that is invalid
for this operation. Common causes include the inability to successfully decode a
parameter element, the presented parameters are not in the expected key=value
format, the value is not a valid regular expression, a required parameter is
missing, multiple instances of a parameter are present on an operation that does
not permit multiple instances of that parameter, or the value is not a valid enum
for the operation.
15 The request body contains a field whose presence or value is inconsistent with the
presence or value of another field in the request body. A prerequisite condition or
dependency among request body fields is not met.
18 The request body contains a field whose presence or value is inconsistent with the
type of the object. Such a requirement is often described in an object’s data model
as the field having a prerequisite condition on a "type", "family", or similar
property that identifies an object as being of a particular type. Such a property is
typically, but not necessarily, immutable.
19 The request body contains a field whose corresponding data model property is no
longer writable. In certain earlier HMC and/or SE versions the property is
writable, but later versions do not allow changing the property through the Web
Services APIs. This could be due to a change in the underlying
system-management model, or the property may have become obsolete.
20 The request body contains a field or value that is directly or indirectly dependent
on the version of the SE that is targeted by or associated with the request
operation, and that SE is not at a version that supports or provides the field or
value.

42 HMC Web Services API

 Level 04a

Reason
HTTP status code code Description
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform the requested action.
3 The ensemble is not operating at the management enablement level required to
perform this operation.
4 The request requires authentication but no X-API-Session header was specified in
the request.
5 An X-API-Session header was provided but the session id specified in that header
is not valid.
| 301 The operation cannot be performed because it targets a CPC that does not support
| Web Services API operations.
404 (Not Found) 1 The request URI does not designate an existing resource of the expected type, or
designates a resource for which the API user does not have object-access
permission. For URIs that contain object ID and/or element ID components, this
reason code may be used for issues accessing the resource identified by the first
(leftmost) such ID in the URI.
2 A URI in the request body does not designate an existing resource of the expected
type, or designates a resource for which the API user does not have object-access
permission. For URIs that contain object ID and/or element ID components, this
reason code may be used for issues accessing the resource identified by the first
(leftmost) such ID in the URI.
3 The request URI designates a resource or operation that is not available on the
Alternate HMC.
4 The object designated by the request URI does not support the requested
operation.
5 The request URI does not designate an existing resource of the expected type, or
designates a resource for which the API user does not have object-access
permission. More specifically, this reason code indicates issues accessing the
resource identified by the element ID component in the URI. Such an element ID
is typically the second (counting left to right) ID component in the URI.
6 A URI in the request body does not designate an existing resource of the expected
type, or designates a resource for which the API user does not have object-access
permission. More specifically this reason code indicates issues accessing the
resource identified by the element ID component in the URI. Such an element ID
is typically the second (counting left to right) ID component in the URI.

Chapter 3. Invoking API operations 43

 Level 04a

Reason
HTTP status code code Description
409 (Conflict) 1 The operation cannot be performed because the object designated by the request
URI is not in the correct state.
2 The operation cannot be performed because the object designated by the request
URI is currently busy performing some other operation.
3 The operation cannot be performed because the object designated by the request
URI is currently locked to prevent disruptive changes from being made.
4 The operation cannot be performed because the CPC designated by the request
URI is currently enabled for DPM.
5 The operation cannot be performed because the CPC designated by the request
URI is currently not enabled for DPM.
6 The operation cannot be performed because the object hosting the object
designated by the request URI is not in the correct state.
8 The operation cannot be performed because the request would result in the object
being placed into a state that is inconsistent with its data model or other
requirements. The request body contains a field whose presence or value is
inconsistent with the current state of the object or some aspect of the system, and
thus a prerequisite condition or dependency would no longer be met.
9 The operation cannot be completed because it is attempting to update an effective
property when the object is not in a state in which effective properties are
applicable. More specifically, the request body contains one or more fields which
correspond to a property marked with the (e) qualifier in the data model, and the
object's effective-properties-apply property is false.
10 The operation cannot be performed because the affected SE is in the process of
being shut down.
11 The operation cannot be performed because it requires a fully authenticated
session and the API session that issued it is only partially authenticated.
| 12 The operation cannot be performed because a feature that prohibits the operation
| is currently enabled. The error-details field of the response body contains an
| error-feature-info object identifying the feature whose current enablement status is
| invalid for the operation. The error-feature-info object is described in the next
| table.
| 13 The operation cannot be performed because a feature required by the operation is
| currently disabled. The error-details field of the response body contains an
| error-feature-info object identifying the feature whose current enablement status is
| invalid for the operation. The error-feature-info object is described in the next
| table.

| The error-feature-info object contains the following fields:

| Table 19. error-feature-info object properties
| Field name Type Description
| scope String Enum The scope of the feature requirement. The valid values are:
| v "cpc" - The feature enablement requirement applies to the CPC
| object involved in the operation.
| v "partition" - The feature enablement requirement applies to the
| Partition object involved in the operation.
| name String Enum The name of the feature requirement.
| v When the scope is "cpc", this is a feature name from the CPC's
| available-features-list property.
| v When the scope is "partition", this is a feature name from the
| Partition's available-features-list property.

44 HMC Web Services API

 Level 04a

Common request processing reason codes

Certain common error conditions can be encountered during the processing of many of the operations of
the API. When they are encountered they are reported using the same HTTP status and reason code by
any operation of the API that may encounter them.

These common request processing reason codes are listed in the following table:

Reason
HTTP status code code Description
500 (Server Error) 0 - 39 An internal processing error has occurred and no additional details are documented.
503 (Service 1 The request could not be processed because the HMC is not currently communicating
Unavailable) with an SE needed to perform the requested operation.
2 The request could not be processed because the SE is not currently communicating
with an element of a zBX needed to perform the requested operation.
3 This request would exceed the limit on the number of concurrent API requests
allowed.

Use of chunked response encoding

For most API operations, the size of the response data is modest and therefore standard HTTP response
payload transfer encoding is used. In this encoding, the length of the entire payload of the response
message is provided in the response before any of the contents of the response payload are written to the
socket connection. But some operations, such as the Get Inventory operation of the Inventory service and
the Get Metrics operation of the Metrics service, can produce very large responses. Use of standard
transfer encoding for these kinds of operations is inefficient for the HMC because it requires the entire
response be generated and buffered before any of it is sent in order to compute and send the total length
of the response body before sending any of the contents of the response data.

To avoid the need for the buffering the entire response, and to instead allow the response to be
transmitted in smaller segments as they are prepared, operations that return large responses use HTTP
chunked response encoding instead. Chunked transfer encoding is an HTTP V1.1 data transfer feature
that allows the payload of the response message to be split into a sequence of smaller parts known as
chunks, with the size of each chunk transmitted as part of the chunk rather than requiring the
transmission of the size of the full response payload.

Chunked transfer encoding is defined in the HTTP/1.1 protocol standard, RFC 2616, cited earlier in this
section.

The HTTP protocol standard requires that all HTTP/1.1 applications (client or server) be capable of
receiving and handling chunked transfer-encoded messages, so the use of this encoding by the API HTTP
server is within the options allowed by the protocol standard. However, since this format may be
unexpected to naively-written applications, its use is limited by the API HTTP server to the special
circumstances that warrant its use to improve performance or efficiency. Therefore, a client application
can safely assume that an operation will not use chunked transfer encoding for its responses unless the
use of this encoding is specifically mentioned in the description of the operation.

Filter query parameters

Some operations allow for the (optional) use of designated query parameters for conveying additional
request parameters. Although query parameters can be used to convey various kinds of additional
request information, most operations that make use of query parameters do so for the purpose of filtering
the response entries to a subset of what would otherwise be returned. For example, this kind of filtering

Chapter 3. Invoking API operations 45

 Level 04a

is typically provided on operations that are described as List operations (e.g. List Virtual Servers of
Ensemble). This section describes the interpretation/handling of filter-type query parameters across all of
the operations of the API.

As would be expected, if an operation is invoked without specifying any of its possible filter-type query
parameters, the operation returns all of the result entries applicable to the request. For example, the List
Virtual Servers of Ensemble operation invoked with no filtering query parameters returns all of the
Virtual Server objects in the Ensemble to which the API user has access.

If one or more filter-type query parameters are specified, the combination of those parameters specifies a
logical match expression that is evaluated against each entry that is a candidate for inclusion in the result
to determine if the entry is included or not. Within that expression, there may be multiple occurrences of
the same-named query parameter and/or there may be occurrences if differently-named query
parameters. The query parameters are interpreted as a logical expression using the following rules:
v Multiple occurrences of the same-named query parameter are interpreted as a group that is connected
by a logical OR operation among all of query parameters with the same name. An entry remains a
candidate for inclusion in the result as long as it matches at least one of the values specified for this
particular query parameter.
v Occurrences of differently-named query parameters are first organized into OR'ed groups as mentioned
above, and then these groups are interpreted as being connected by logical AND operations. Thus an
entry is included in the result only if it matches at least one value from each of the differently-named
groups of parameters.
v As an example, a query string of “name=fee&type=fie&name=foe&type=fum” is interpreted as
specifying the expression (name=fee OR name=foe) AND (type=fie OR type=fum). Note that the order
in which the query parameters appear in the string is not important.

As a filter-type query parameter is applied against a candidate entry, it is determined to match or not as
follows:
v If the query parameter is of data type String, the parameter's value is interpreted as a regular
expression pattern and is considered to match if the corresponding String property of the candidate
entry matches the pattern.
v If the query parameter is of data type String Enum, the parameter's value is compared against the
corresponding Enum property of the candidate entry and is considered to match if they are exactly the
same value.
v If the query parameter is of data type Boolean, the parameter's value is compared against the
corresponding Boolean property of the candidate entry and is considered to match if they are both true
or both false.

Regular expression syntax

The values of String-type filtering query parameters are interpreted as regular expressions. The regular
expression syntax used is the same as that used by the Java programming language, as specified for the
java.util.regex.Pattern class. Documentation on that syntax can be found at on the following web page:
http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

46 HMC Web Services API

 Level 04a

Chapter 4. Asynchronous notification

The Web Services API includes an asynchronous notification facility by which client applications may
subscribe to and receive notification messages regarding a set of predefined management events. These
events include:
v Addition and removal of managed objects to/from the inventory of resources that are managed by the
HMC.
v Changes to specified properties of managed object instances.
v Changes to the operational status of managed objects.
v Completion of asynchronously processed jobs.
v Addition of entries to the HMC's audit log.
v Addition of entries to the HMC's security log.
v New and refreshed operating system messages.

The zManager notification facility is based on the Java Message Service (JMS) architecture and API for
exchanging messages among two or more applications.

JMS basics
In the JMS model, message-based communication between producing and consuming applications is
coordinated by an intermediate component known as a message broker that acts as the clearinghouse for
message exchange. The message broker provides a registry of the available destinations to which
messages can be posted, and a store for messages that have been posted but not yet consumed.

Applications acting in the role of message producer create messages and post them (via the broker) to the
destination appropriate for the type of message. The messages are associated with the destination and
retained by the broker until they have been consumed by interested applications.

Applications acting in the role of message consumer connect to a message destination (again, via the
broker) in order to express interest in receiving messages posted to it. As messages are posted to the
destination by producers, the broker makes the messages available to interested consumers which then
receive and process the message.

In the Web Services API notification facility, the HMC acts both as the message broker and the message
producer for API notification messages. API client applications act as message consumers.

For the broker function, the HMC includes an integrated JMS message broker implementation based on
Apache ActiveMQ, an open, standards-based implementation of JMS. This integrated broker is configured
to allow internal HMC function to act as message producers, and to allow external applications to
connect as message consumers. However, external applications cannot produce and send messages using
the HMC integrated broker.

Connecting to the API message broker

As part of the Web Services API, the HMC provides an integrated JMS message broker based on Apache
ActiveMQ Version 5.2.0. This message broker is active on the HMC whenever the Web Services API is
enabled.

When active, the integrated broker listens for client connections using the following transports supported
by ActiveMQ:
v OpenWire flowing over SSL connections, listening port: 61617.

© Copyright IBM Corp. 2017, 2018 47

 Level 04a

v STOMP (Streaming Text Oriented Messaging Protocol) flowing over SSL connections, listening port:
61612.

The broker is enabled for the SSL version 3 and TLS version 1 protocols on these SSL ports.

The listening ports for the message broker are fixed port numbers and are not subject to customer
reconfiguration. Thus, client applications can treat them as well-known port numbers rather than
requiring customer input when configuring the networking parameters the client will use to connect to
the HMC.

In order to connect to the integrated message broker, clients must provide certain authentication
information for the HMC user making the connection. If the HMC user is configured to use multi-factor
authentication, then the client must provide information about the HMC user's API session that is to be
associated with the message broker connection. The user name field in the connection request must
contain the API session ID, and the password field must contain the session-specific authentication
credential. Both of these are available in the response body of the Logon operation that created the API
session: the api-session and session-credential fields, respectively.

If the HMC user is not configured to use multi-factor authentication, then the client may provide the
authentication information as described immediately above, or it may provide a valid HMC user name
and logon password in order to identify the HMC user making the connection. The user name and
password are validated using the standard HMC user authentication mechanisms before allowing the
connection to succeed.

The integrated message broker does not allow any anonymous or unauthenticated connections.

Per-session notification topics

As part of its access control enforcement, the Web Services API limits the distribution of notification
messages to clients that have object-access permission to the managed object for which the notification
was generated.

In order to accomplish this, the API does not define a single (or fixed number of) notification topics to
which all messages are posted and from which any or all clients can receive messages. Rather, the API
uses per-session notification topics.

In this approach, each API session is associated with a set of JMS destinations that are created by the
HMC when the session is created or other actions are performed using the session, and are used for
providing notifications destined to that session. The names of the object notification and job completion
destinations are returned as part of the results from the Login operation. The names of all destinations
available to a session are returned by the Get Notification Topics operation. Each session has the
following per-session notification destinations:
v An object notification topic, used by the HMC to send notifications that pertain to the inventory and
status of managed objects that this session has permission to access.
v A job notification topic, used by the HMC to send notifications that pertain to the status of
asynchronous operations that are initiated by this session.
v An audit notification topic, used by the HMC to send notifications that pertain to the HMC's audit log,
but only if the client has permission to the Audit and Log Management task. Without the required
task permission, there is no such destination available to the session.
v A security notification topic, used by the HMC to send notifications that pertain to the HMC's security
log, but only if the client has permission to the View Security Logs task. Without the required task
permission, there is no such destination available to the session.
v An operating system message notification topic, used by the HMC to send notifications that pertain to
new and refreshed operating system messages. More than one topic of this type can exist for a single
API session.

48 HMC Web Services API

 Level 04a

Unlike the other topic types, topics of this type are not created by default when the session is created.
They are created when the user targets the Open OS Message Channel operation at a Logical Partition
or Partition object. Operating system messages begin to flow after the user first connects to the topic. If
refresh messages are desired, they are published to the topic immediately following a connection being
established to the topic. New messages are sent as they are received. When there are no connections
remaining to the topic, the flow of messages stops. The topic will persist, allowing for a reconnect. If
the user reconnects, messages will flow as if it was the first connect. The topic is destroyed only when
the user performs the Logoff operation or the session is otherwise destroyed.

The session is also associated with an HMC user (identified during API session login) that in turn has a
set of object-access permissions defined for it that determine the managed resources that it is authorized
to access. The HMC user also has a set of task permissions defined for it that determine the tasks that it
is authorized to perform.

As notification messages are created for managed resource changes or other events, they are distributed
to sessions according to the object-access permissions of those sessions. More specifically, when a
notification is generated pertaining to some managed resource, it is published to the object notification
topics of all sessions for which the related API user has object-access permission to that managed
resource, and is omitted from the object notification topics of sessions for which the user does not have
object-access permission. As a result, a particular API session will have access to all notifications for all
managed resources to which its API user has access permission, but will not have access to notifications
for managed resources that it does not.

Notification messages for job completion are sent only to the job notification topic of the API session that
initiated the asynchronous processing represented by the job.

Notification message formats

Six types of notification messages are provided by the API. The JMS messages created for all types of
notifications share a common set of message characteristics and header fields, which are extended with
additional header fields and message body formats that vary by the type of notification.

Common message characteristics

The characteristics described in this section apply to all notification messages published by the Web
Services API.

Message format
The following JMS message characteristics apply to all notification messages sent by the Web Services
API. These characteristics are echoed in the message themselves in the values of the standard JMS
message header fields.

Characteristic Description
Destination The per-session object or job notification topic as indicated below for each type of notification.
Message type Text message. The contents of the body vary by the type of notification.
Delivery mode Nonpersistent.
Expiration No expiration.
Priority 4 (highest normal priority)
Message ID A unique message ID for the message.
Correlation ID Not set by the API.
Timestamp The time, from the HMC's perspective, that this message was sent.

Chapter 4. Asynchronous notification 49

 Level 04a

In addition to the standard JMS message headers, the following additional message properties are
provided in all notification messages to allow for message selection:

Message
Property Name Description
notification- The type of notification contained in this message, varies by notification type.
type
session- The sequence number of this notification within the session. This number starts at 0 when the API
sequence-nr session is created, and is incremented each time a notification message is published to this
session.
global- The sequence number of this notification from the HMC. This number starts at 0 when the HMC
sequence-nr is started, and is incremented each time a notification message is published to any API session.
object-uri The current value of the object-uri property (canonical URI) of the managed object for which the
notification is being emitted.
object-id The current value of the object-id property (durable unique identifier) of the managed object.
element-uri The current value of the element-uri property of the element object for which the notification is
being emitted. This message property is included only when the message pertains to an element
object of a managed object.
element-id The current value of the element-id property (local identifier) of the element object. This message
property is included only when the message pertains to an element object of a managed object.
class The current value of the class property (kind of object) of the object, i.e. the kind of object for
which the notification is being emitted.
name The current value of the name property (display name) for the object to which the notification
pertains.
Note: Note: In some circumstances the name property may be unavailable, in which case this
field is set to an empty string. This may occur, for example, if a property change occurs and is to
be reported on very shortly before (essentially concurrent with) the removal of that object from
the inventory.

When a notification message pertains to an element object, the message includes element-uri and
element-id fields in addition to object-uri and object-id fields. The element-* fields identify the element
object instance while the object-* fields identify the containing managed object instance. In this case, the
class field provides the class of the element object, and the name field provides the name of the element
object.

When a notification message pertains to a managed object, the message contains object-uri and object-id
fields but not the element-* fields and the class field provides the class of the managed object and the
name field provides the name of the managed object.

Grouping of notifications
A particular managed resource may often experience a series of changes that occur in rapid succession.
This might occur, for example, when a user uses an object's Details task in the HMC UI to make a set of
changes to the object's properties and then selects the Finish button to complete the task. All of the
pending property changes collected by the task will be made on the managed object in very quick
succession in response to the Finish button being selected, rather than before as the user was interacting
with the task.

In order to reduce the notification traffic in these situations, the notification messages have been designed
to allow the HMC to report multiple changes of the same type (e.g. property changes, status changes) for
the same managed resource in a single message rather than generating a distinct message for each
change. In order to do such grouping, the HMC may delay generation of a notification message for a
change for a brief period of time in order to allow coalescing of that change report with others that occur
for the same managed resource within the coalescing time window. This optimization will be performed
while maintaining the following characteristics:

50 HMC Web Services API

 Level 04a

v Grouping of notifications may be done for property change, status change, operating system message,
and log entry notifications, but will not be done for other notification types.
v Notifications will be buffered for a maximum of 1 second.
v The grouping of change reports will not obscure a client's ability to correctly observe the temporal
ordering of the individual changes made to a particular object or between objects based on the
messages sent to a session. That is, notification messages will always be generated so that the ordering
of the messages as determined by their session sequence numbers reflects the temporal order in which
the changes were actually made. All of the changes reported to a session in a message with a lower
session sequence number will have occurred before any of the changes reported in a message with a
higher session sequence number. Further, the ordering of change reports within a particular message
reflects the order in which they occurred to that object as well.
v Coalescing of multiple changes into a single notification message will occur for at most a single
pending notification message (thus, of a single type) at a time. If a need arises to report a change of a
different type than is currently pending (for example, a need to report a status change when there is
currently a set of pending property change reports), coalescing will end for that pending message and
it will be posted to notification topics as appropriate. This is necessary in order to maintain the API
client's ability to correctly observe temporal ordering.
v The grouping of change reports into notification messages occurs independently for each session, so
that one session may receive a different distribution of change reports across notification messages than
another session.

The degree to which message grouping occurs or not depends on the timing of changes and possibly
other considerations and thus is to be strictly considered an optimization and not guaranteed behavior.
Client applications should infer no particular semantic significance to change reports being delivered in a
single message vs. a sequence of messages.

Status change notification

A Status Change notification is emitted by the API to report changes to the status property of a managed
object.

Characteristic Description
Destination The per-session object notification topic for each API session that is authorized to receive
the notification.

In addition to the common JMS message headers described above, the following additional message
properties are provided for this type of notification:

Message property name Description

notification-type Contains the value "status-change".

The body of a Status Change notification message is a JSON representation of an object that contains the
following fields and values:

Field name Type Description

change-reports Array of An array of nested change-report objects, the format of which is described in
objects the next table. The order in which these objects appear in this array reflects
the temporal order in which the changes occurred.

Each nested change-report object has the following fields and values:

Chapter 4. Asynchronous notification 51

 Level 04a

Field name Type Description

old-status String The old (previous) value of the status property for the object. The value of
this field will be one of the possible enumeration values for the status
property as defined for this class of object.
old-additional-status String The old (previous) value of the additional-status property for the object. The
value of this field will be one of the possible enumeration values for the
additional-status property as defined for this class of object.
new-status String The new (current) value of the status property for the object. The value of
this field will be one of the possible enumeration values for the status
property as defined for this class of object.
new-additional-status String The new (current) value of the additional-status property for the object. The
value of this field will be one of the possible enumeration values for the
additional-status property as defined for this class of object.
has-unacceptable- Boolean The value of the has-unacceptable-status property of the object, based on its
status new status. If true, the object is now considered to have unacceptable status
because its current status is not one of the configured acceptable status
values for this object.

Property change notification

A Property Change notification is emitted by the API to report changes to the properties of a managed
object where the data model description indicates that modification notification support (qualifier “pc”) is
available for that property.

Characteristic Description
Destination The per-session object notification topic for each API session that is authorized to receive the
notification.

In addition to the common JMS message headers described above, the following additional message
properties are provided to allow for message selection:

Message property
name Description
notification-type Contains the value "property-change".
property-names Blank-separated list of the names of the properties for which change reports are provided in
the body of this notification message. The list always includes a leading and trailing blank
so that a property name can be specified as a blank-delimited word in a message selector to
avoid matching unintended properties that have the desired property name as a substring.

The body of a Property Change notification message is a JSON representation of an object that contains
the following fields and values:

Field name Type Description

change-reports Array of An array of nested change-report objects, the format of which is described in the
objects next table. The order in which these objects appear in this array reflects the
temporal order in which the changes occurred.

Each nested change-report object has the following fields and values:

52 HMC Web Services API

 Level 04a

Field name Type Description

property-name String The name of the property (as specified in the object's data model) that has
changed.
old-value Based on If the property is not a container-type or write-only property, this field contains
model the old (previous) value of the property for the object. The value of this field will
be of the data type indicated for this property in the object's data model.

If the property is a container-type property (i.e. marked with the (c) qualifier),
this field does not provide the complete previous value. Rather, it provides an
array of entries that have been removed from the value of the container property.
The value of these entries will be of the data type indicated for the property in
the object's data model. If no entries have been removed, null is provided.

If the property is a write-only property (i.e. marked with the (wo) qualifier), this
field does not provide the value of the property. Rather, this field always
contains null.
new-value Based on If the property is not a container-type or write-only property, this field contains
model the new (current) value of the property for the object. The value of this field will
be of the data type indicated for this property in the object's data model.

If the property is a container-type property (i.e. marked with the (c) qualifier),
this field does not provide the complete new value. Rather, it provides an array
of entries that have been added to the value of the container property. The value
of these entries will be of the data type indicated for the property in the object's
data model. If no entries have been added, null is provided.

If the property is a write-only property (i.e. marked with the (wo) qualifier), this
field does not provide the value of the property. Rather, this field always
contains null.

Inventory change notification

An Inventory Change notification is emitted by the API to report the addition or removal of a managed
object to/from the current inventory of resources that are being managed by zManager. This occurs when
managed resources are created or deleted, but also may occur in other situations, such as when zManager
reestablishes its inventory of (already-existing) managed resources upon restart of the primary HMC.

For some kinds of managed objects, an Inventory Change notification is also emitted by the API to report
the addition or removal of an element of a managed object. Such notifications do not occur for all
elements, but rather only when specifically described in the documentation for a class of managed object.

Because an Inventory Change notification may be generated more than once for the same conceptual
object, these notifications cannot be interpreted as designating a resource creation action.

Characteristic Description
Destination The per-session object notification topic for each API session that is authorized to receive the
notification.

In addition to the common JMS message headers described above, the following additional message
properties are provided to allow for message selection:

Message property
name Description
notification-type Contains the value "inventory-change".
name Not provided for this notification. Always an empty string.

Chapter 4. Asynchronous notification 53

 Level 04a

Message property
name Description
action The value "add" when the object has been added to the inventory, or "remove" when it is
being removed.

The body of an inventory change notification is null.

Job completion notification

A Job Completion notification is emitted by the API to report that the processing of an operation that
runs asynchronously to the client application has ended.

Asynchronous operations are those that complete with an HTTP status code of 202 (Accepted) when
requested by the client. A Job Completion Notification message is sent to the API session that initiated
the job when such an operation completes or is canceled, and provides to the client application the URI
of the job that has completed or been canceled so the client application can use the Query Job Status
operation to obtain results for the job.

Characteristic Description
Destination The per-session job notification topic for each API session that is authorized to receive the
notification.

In addition to the common JMS message headers described above, the following additional message
properties are provided to allow for message selection:

Message property
name Description
notification-type The value "job-completion".
job-uri The URI identifying the asynchronous job that has just completed execution or has been
canceled.

The body of a job completion notification is null.

Log entry notification

A Log Entry notification is emitted by the API to report the addition of a log entry to its corresponding
console log.

Characteristic Description
Destination The audit notification topic or security notification topic for each API session that is
authorized to receive the notification.

In addition to the common JMS message headers described above, the following additional message
property is provided to allow for message selection:

Message property
name Description
notification-type Contains the value "log-entry".

The body of a Log Entry notification message is a JSON representation of an object that contains the
following fields and values:

54 HMC Web Services API

 Level 04a

Field name Type Description

log-entries Array of An array of nested log-entry-info objects, the format of which is described in
objects Table 267 on page 499. The order in which these objects appear in this array
reflects the temporal order in which the log entries were created.

Operating system message notification

An operating system message notification is emitted by the API to report new or refreshed operating
system messages.

Characteristic Description
Destination One of the os-message-notification topics associated with the API session.

In addition to the common JMS message headers described above, the following additional message
property is provided to allow for message selection:

Message property
name Description
notification-type Contains the value "os-message".

The body of an operating system message notification message is a JSON representation of an object that
contains the following field and value:

Field name Type Description

os-messages Array of An array of nested os-message-info objects, the format of which is described in
objects the next table. The order in which these objects appear in this array reflects the
temporal order in which the messages were created.

Each nested os-message-info object has the following fields and values:

Field name Type Description

sequence-number Long The sequence number assigned to this operating system message by the
HMC. Although sequence numbers may wrap over time, this number can
be considered a unique identifier for the message.
message-text String The text of the new or refreshed operating system message.
message-id String The message identifier of the operating system message.
timestamp Timestamp The timestamp represents the date and time when the operating system
message was created. A value of -1 is returned if this information is not
available from the corresponding operating system.
sound-alarm Boolean Specifies whether the operating system message should cause the alarm to
be sounded (true) or not (false).
is-priority Boolean Specifies whether the operating system message is a priority message (true)
or not (false). A priority message indicates a critical condition that requires
immediate attention.
is-held Boolean Specifies whether the operating system message is a held message (true) or
not (false). A held message is one that requires a response.

Chapter 4. Asynchronous notification 55

 Level 04a

Field name Type Description

prompt-text String Specifies the prompt text that is associated with this operating system
message or null indicating that there is no prompt text for this operating
system message. The prompt text is used when responding to a message.
The response is to be sent as an operating system command where the
command is prefixed with the prompt text and followed by the response to
the message.
os-name String (1-8) Specifies the name of the operating system that generated this operating
system message or null indicating there is no operating system name
associated with this operating system message. This name is determined by
the operating system itself and may be unrelated to the name of the
partition in which the operating system is running.
is-refresh Boolean Specifies whether the message is a new (false) or a refresh message (true).
When the user connects to an os-message-notification topic, operating
system messages that already exist are sent as refresh messages, if desired
by the user.

56 HMC Web Services API

 Level 04a

Chapter 5. Data model definitions

This chapter covers data model concepts and shared data model schema elements.

Data model concepts

zManager provides resource management and control functions for the various resources that comprise
an ensemble environment. In performing these functions, zManager establishes a separation between
those aspects of resource management that are handled entirely by system firmware, and the other
aspects for which customer or installation visibility, configuration and control is appropriate.

In order to specify the external aspects in a succinct way, the web Services API is described in this
document in terms of a conceptual data model that it offers for the resources that it manages. This data
model is an information structuring technique that conceptually defines the kinds of resources that are
managed by zManager and for each, the information that is available for and the operations that can be
performed on resources of that kind. This data model is intended to provide the complete perspective
that clients of the API can have regarding the logical resources of the system while insulating them from
implementation details.

Objects in the data model

The manageable resources of the environment are represented in the management system as entities
referred to as objects. Each distinct manageable resource is represented by a separate object instance, and
the life cycle of an instance corresponds with the lifecycle of the manageable resource it represents. For
example, for physical entities, such as an IBM blade in a zBX, the object that represents it are created
implicitly when the physical entity is attached to and configured to be (or entitled to be) part of the
system. This object continues to exist so long as the IBM blade remains entitled on the system. For some
logical entities, such as the virtualization management functions on an IBM blade, the object that
represents it (virtualization host) is also implicitly rather than explicitly created. For other logical entities,
such as a virtual server on an IBM blade, the creation of the management model object instance for it is,
in fact, the mechanism that triggers the creation of the corresponding manageable resource in the system.

There are different kinds of manageable physical or logical resources in the system, and each kind
manifests different observable characteristics. As a result, there are different classes of objects in the data
model. Objects of the same class represent the same kind of resource and provide a defined set of
properties that capture the attributes of that kind of resource that the Web Services API exposes.

Managed objects and element objects

The object classes defined in the data model fall into one of two main categories: managed object classes
(or simply managed objects), and element object classes (element objects).

These two categories are very similar in that they are both, ultimately, unordered collections of named
properties that capture the key attributes of a resource instance. The categories differ primarily in how
prominently they are handled in the API: the way that instances of them are designated to perform
operations on them, and the degree to which API facilities such as inventory and change notification can
be offered for objects in that category.

Managed objects are the first-class entities in the data model and the API. They represent the primary
manageable resources of the system, such as ensembles, blades, virtual servers and workloads. These
kinds of objects typically appear prominently in the main displays of the HMC user interface.

Instances of managed objects are registered and indexed in the zManager managed object registry, and
thus can be directly referenced by URIs that form a relatively "flat" namespace. The URI of a managed

© Copyright IBM Corp. 2017, 2018 57

 Level 04a

object designates its object instance based on its class and a unique, durable, UUID-based identifier called
an object ID. For example, the URI of a virtual server is of the form /api/virtual-servers/{vs-object-
id} where the identifier at the end of the URI is globally unique. Inventory change, property change, and
status change notifications can be generated for managed objects.

In comparison, element objects represent the secondary or more-detailed aspects of the system. Examples
include the virtual network adapters of a virtual server, or the performance policies of a workload. These
kinds of entities do not generally appear in the main displays of the HMC user interface, but rather are
displayed only within particular management tasks offered by the UI.

Instances of element objects are not directly registered in the zManager object registry, but rather are
associated with or “attached to” some containing or related managed object instance. As a result, access
to these elements is indirect, through the containing managed object. The URIs that designate element
objects are hierarchical in nature, with the leftmost part of the URI identifying the managed object to
which the element is attached. For example, the URI for a virtual disk of a virtual server is of the form
/api/virtual-servers/{vs-object-id}/virtual-disks/{disk-id} in which the {disk-id} at the end is only
necessarily unique within the context of the related virtual server. Inventory, property and status change
notifications are not provided for element objects. Instead, when changes to elements are reported, those
changes are done via property change notifications emitted for the associated managed object.

Properties in the data model

Objects in the management system contain, fundamentally, unordered collections of name/value pairs
called properties that capture the key characteristics of the manageable resources they represent. The
defined set of named properties that are maintained for a particular kind of resource constitutes the
specification of the data model class for that kind of resource.

As a result, in the chapters that follow, the description of the management interfaces for a class of
resource begins with a data model section that specifies the properties that are exposed by the API for
that kind of resource.

Each property has a name, a data type, and a semantic description in prose.

The property name is the programmatic identifier of the property. This identifier is used within requests
and responses to indicate that a field represents a particular property of the data model. It is the “name”
part of the name/value pair that is the property.

The property data type indicates the kind of information that can be represented by the property, just as a
variable's data type indicates the kind of information that can be stored in a variable. The data type
provides information on the nature of the “value” part of the name/value pair that is the property.

Property characteristics
Properties are classified as being either writable or read-only from the perspective of an API client
application.

Writable properties are ones that can have their values read by Get <class> Properties or similar
operations and can also have their values directly changed by Update <class> Properties operations.
Properties that are classified as write-only can have their values directly changed by Update <class>
Properties operations, but cannot have their values read by using Get <class> Properties or similar
operations. Properties that are classified as read-only can have their values read by using Get <class>
Properties or similar operations, but cannot have their values changed directly.

Although properties that are classified as read-only cannot have their values changed directly, their
values may nonetheless be affected by other operations supported by a class of object. For example, a
class of object might include an is-enabled property that is classified as read-only because the enabled
state of the resource cannot be affected by a simple Update <class> Properties operation on that

58 HMC Web Services API

 Level 04a

is-enabled property. However, this object might also define a Change State or Enable operation that can
perform this enabling, and as a side effect will alter the value of the is-enabled property.

In addition to the read-only vs. writable classification, properties defined for a managed object also can
differ in whether changes to them result in property change or status change notifications being emitted
for the managed object or not. For properties that have property or status change support, these
notifications are emitted asynchronously by the API any time the value of the property changes, whether
that change was made via this API, the HMC UI, or implicitly by the system. Changes to the values of
properties for which change notification support is not provided do not result in such notifications.

Most objects have properties that are primarily configuration data. However, for some objects, certain of
those configuration-related properties may at times also have a transient, runtime counterpart property in
effect whose value can be different than the preserved configuration or base value. That transient,
runtime counterpart property is known as an “effective” property and is identified as such in the object's
data model by the (e) qualifier. The name of an effective property is formed by prepending “effective-” to
the name of its corresponding base property. Whether an object's effective properties are applicable at any
point in time is determined by the state of the object or the state of the system or related objects and is
described in that object class' section of this document. The object's effective-properties-apply property
indicates whether effective properties are currently applicable. If effective-properties-apply is false, the
value of an effective property is the same as its corresponding base property and the effective property
may not be altered by an Update <class> Properties operation.

In some cases, an object in the management system may have properties whose values are unwieldy to
provide or expensive to obtain and further may not be of general interest in typical API client use cases.
To allow the handling of such properties to be optimized they are represented by a special kind of
property termed a pseudo property. A pseudo property is conceptually one of the characteristics of a class
of object and is thus documented in the data model for the object (with a (p) qualifier). However, the
name and value of a pseudo property is not included in the response to a Get <class> Properties
operation or in the inventory service data for that class of object. Instead, class-specific operations are
provided in order to obtain the current value of the property when needed by an API client. As for
normal properties, property change notifications may be generated for changes to a pseudo property if
indicated in the data model.

In the tables of properties that appear within this document, the characteristics of properties are indicated
by qualifier annotations in parenthesis following the property name. The qualifiers have the following
meanings:

Qualifier
notation Description
(w) The property is a writable property. Any property that lacks this qualifier and the (wo) qualifier is
considered read-only and thus is not directly modifiable.
(wo) The property is a write-only property. Any property that lacks this qualifier and the (w) qualifier is
considered read-only and thus is not directly modifiable.
(ro) Although this property is writable when present in other managed object classes, it is read only in
this class. This qualifier is only used when a managed object class specializes the definition of a
base managed object property and overrides the writable characteristic of the base definition.
(p) The property is a pseudo property. Its current value is omitted from the response to a Get <class>
Properties operation or inventory service data for the object, but can be obtained by a class-specific
operation.
(pc) Change to this property's value will result in Property Change notifications.
(c) The property is a container-type property for which deltas (changes) are reported in Property
Change notifications rather than complete old and new values.
(sc) Change to this property will result in Status Change notifications.

Chapter 5. Data model definitions 59

 Level 04a

Qualifier
notation Description
(mg) This property represents a performance or utilization metric of the object that is included in a
metric group available via the Metrics Service of this API. The value of this property may change
very frequently and, therefore, property change notifications are not emitted for changes to this
property. Client applications interested in obtaining metric information frequently should obtain
this information through use of the Metrics Service of this API.
(e) The property is an effective property.

Shared data model schema elements

The data-model schema fragments in this section define groups of properties that are used in common
ways in specifying the data models for the managed object classes defined in the API.

The description of the data model for a specific object class specifies the shared schema elements it is
incorporating within the data model section of that description, if any. It will also include a description of
the specializations that apply to that class's use of the shared schema, such as additional constraints on
properties, class-specific values for properties, etc.

Base managed object properties schema

This data-model fragment contains the basic properties that are present in the representation of many of
the managed object types that represent manageable resources.

Name Qualifier Type Description

object-uri — String The canonical URI path that designates this managed object instance and
(1-255) serves as the primary reference and retrieval key for this instance. The
URI path is formed based on a unique and permanently-assigned object
ID (see the object-id property in the next row of this table), and as
result, an object's URI path will not change as a result of changes to
properties of the object. Further, this canonical URI path is independent
of the containment hierarchy and thus will not change if this object
instance is moved within the hierarchy.
object-id — String (36) The object identifier for the managed object instance. This value is
unique in space and time, and is permanently associated with this
instance while it is managed by this HMC or its associated alternate
HMC. (If the instance is removed from this HMC and later managed by
another HMC, it will have a new and different object identifier when
managed by that other HMC.) It is generated by zManager and assigned
when the managed resource is created or first discovered, and is
immutable thereafter. As example, a managed object's object ID will not
change as a result of changes to display name, changes in the location of
this resource in the containment hierarchy, or across restarts of the HMC.
parent — String The canonical URI path of the managed object that is conceptually the
(1-255) parent of this object in the containment hierarchy. This property is null
for objects that do not have a parent.
class — String The class of resource represented by this managed object. Each distinct
(1-32) class of resource has a different type name, while all instances of the
same type share the same type name. The specific value used for a class
of object is specified in the data model section for that object type.
Example: "virtual-server".

60 HMC Web Services API

 Level 04a

Name Qualifier Type Description

name (w)(pc) String The current display name of the managed object as defaulted or
(1-64) specified for the object. This is the simple name of this object, not
qualified by containment hierarchy. This name must consist only of
alphanumeric characters and the following special characters: period (.),
hyphen (-), at sign (@), underscore (_), and space. It must not begin or
end with a space. Some resource types do not support the setting of a
user-assigned display name. For such objects, this property is not
settable, and instead always provides a name assigned by the HMC or
SE.
description (w)(pc) String Arbitrary text providing additional descriptive information about this
(0-1024) managed resource. This information is retained for the resource and may
be shown as part of the object's details on the user interface, but is
otherwise not generally used by zManager. This property may be null.
is-locked (pc) Boolean The object is locked and thus disruptive actions or tasks cannot be
performed on it.
effective- — Boolean The object is currently in a state in which effective properties are
properties- applicable. As this property is only meaningful for object classes whose
apply data model includes effective properties, it is only included for those
object classes.

Operational status properties

Many (but not all) classes of managed objects support the concept of operational status. That is they
maintain information about the current functional state (Not Communicating, Not Operating, etc.) of the
managed resource and whether that current functional state is considered acceptable (not alert causing) or
not. If a class of object supports the operational status concept, it provides the standard properties
defined in the following table (referred to as the operational status properties) in addition to those
defined earlier in this section.

Unless stated to the contrary, any object class data model that includes the base managed object
properties schema should be understood to also provide these operational status properties as well. For
object classes for which that is not the case, the data model description will specifically point out that
operational status and thus these operational-status-related properties are not provided for that object.

The operational status properties are as follows:

Name Qualifier Type Description

status (sc) String The current operational status of the managed resource. The possible
Enum status values vary by managed object class and are specified in the
description of each managed object class that provides this property.
additional- (sc) String A qualifier to the status property used by selected object classes to
status Enum provide finer grained operational status tracking.
acceptable- (w)(pc) Array of The set of operational status values that the managed resource can be in
status String and be considered to be in an acceptable (not alert causing) state.
Enum
has- (sc) Boolean If true, the current operational status of the managed resource is not one
unacceptable- of the acceptable statuses for this resource.
status

Chapter 5. Data model definitions 61

 Level 04a

62 HMC Web Services API

 Level 04a

| Chapter 6. Firmware features

| This chapter describes firmware features.
|
| Firmware feature concepts
| Starting with HMC version 2.14.0 and API version 2.23, features can be enabled for specific objects. To
| indicate this, an available-features-list property is introduced to the objects that are affected. These
| features may be enabled by default from a specific HMC or SE version onwards or enabled by using
| standard feature enablement mechanisms.

| These features affect certain API operations as documented here. API clients should query the enablement
| of these features on a system and choose the operations accordingly.

| The enablement of a feature might mean that the API clients have to use new API operations or new
| properties in existing API operations. It might also indicate that some of the existing API operations and
| properties will not be supported.

| If an API operation is not supported when a feature is enabled, invoking the API operation on an object
| where the feature is enabled would result in a standard status code 409 (Conflict) with a standard reason
| code 12.

| If an API operation is supported only when a feature is enabled, invoking the API operation on an object
| where the feature is disabled would result in a standard status code 409 (Conflict) with a standard reason
| code 13.

| If an API operation targeting an object whose existence is controlled by a feature is invalid given the
| enablement of the feature, a standard status code 404 (Not Found) with standard reason code 1 (for
| managed objects) or 5 (for element objects) is returned.

| The following section describes the features that are currently available.

| dpm-storage-management
| This feature is applicable for the CPC and Partition objects. The Get CPC Properties and Get Partition
| Properties operations can be used to query if the feature is enabled or disabled.

| When this feature is enabled, management of FICON storage is available. FCP and FICON virtual storage
| resources are defined in Storage Groups which are then attached to Partitions. A Partition that has this
| feature enabled has no HBAs visible to an API client or on the UI.

| When this feature is disabled, FICON storage is not available and FCP virtual storage resources (HBAs)
| are attached directly to Partitions.

| The following API operations are affected and will return status code 409 (Conflict) with reason code 12
| when they are invoked on an object on which the "dpm-storage-management" feature is enabled.
| v Create HBA
| v Export WWPN List
| v Dump Partition

| The following API operations are affected and will return status code 404 (Not Found) with reason code 5
| when they are invoked on an HBA object on which the "dpm-storage-management" feature is enabled.

© Copyright IBM Corp. 2017, 2018 63

 Level 04a

| v Delete HBA
| v Update HBA Properties
| v Get HBA Properties
| v Reassign Storage Adapter Port

| There are new API operations introduced with the feature. They are defined in the following sections
| under Chapter 10, “Dynamic Partition Manager (DPM),” on page 137:
| v “Storage Site operations summary” on page 142
| v “Storage Fabric operations summary” on page 142
| v “Storage Switch operations summary” on page 143
| v “Storage Subsystem operations summary” on page 143
| v “Storage Control Unit operations summary” on page 144
| v “Storage Group operations summary” on page 145

| In addition, the following new API operations are introduced with the feature and are defined in
| “Partition operations summary” on page 139:
| v Start Dump Program
| v Attach Storage Group to Partition
| v Detach Storage Group from Partition

| These operations will return status code 409 (Conflict) with reason code 13 when they are invoked on an
| object on which the "dpm-storage-management" feature is disabled.

64 HMC Web Services API

 Level 04a

Part 2. General services

Topics in this part describe the general services available for the Web Services API.

Topics covered in this part are:

v Chapter 7, “General API services,” on page 67
v Chapter 8, “Inventory and metrics services,” on page 87
v Chapter 9, “Metric groups,” on page 103

© Copyright IBM Corp. 2017, 2018 65

 Level 04a

66 HMC Web Services API

 Level 04a

Chapter 7. General API services

This chapter describes the services that are provided by the Web Services API for creating and deleting
API sessions and performing other general functions.

General API services operations summary

Table 20. General API services: operations summary
Operation name HTTP method and URI path
“Query API Version” GET /api/version
on page 68
“Logon” on page 70 POST /api/sessions
“Establish Shared POST /api/sessions/operation/establish-shared-secret-key
Secret Key” on page
75
“Logoff” on page 76 DELETE /api/sessions/this-session
“Get Notification GET /api/sessions/operations/get-notification-topics
Topics” on page 77
“Query Job Status” GET /api/jobs/{job-id}
on page 80
“Delete Completed DELETE /api/jobs/{job-id}
Job Status” on page
83
“Cancel Job” on page POST /api/jobs/{job-id}/operations/cancel
84

Table 21. General API services: URI variables

Variable Description
{job-id} The identifier of an asynchronous job associated with this user, as returned in the
response of the operation that initiated the job.

Session management services

Almost all operations of the Web Services API are requested and carried out in the context of an API
session that is used for determining the client's authority to access managed resources and perform
requested operations. It is also used to scope the delivery of asynchronous notifications and manage
WebSocket instances. An API session is an HMC concept that is independent of any layers on top of
network-related considerations such as a TCP/IP socket connection. As a result, a single API session may
span multiple TCP/IP socket connect/disconnect sequences from the same client.

Sessions are created upon request from a client by using the Logon operation, and may be explicitly
terminated by a client using the Logoff operation. Sessions may also be terminated by the HMC due to
inactivity when no requests are made using the session over a certain period of time. (The default session
timeout is 6 hours, but it is configurable on a per-user basis.) However, termination of a session due to
inactivity will not occur as long as a client application uses the API's notification facility to maintain a
JMS subscription to one or more of the session's JMS notification topics. The existence of such a
subscription is considered by the HMC to indicate that a client is still using the session and thus it is not

© Copyright IBM Corp. 2017, 2018 67

 Level 04a

terminated even if no requests are made using it. The existence of an open WebSocket associated with the
API session will also prevent it from being considered inactive.

The scope of a session is the particular HMC instance on which it was created via a Logon operation.
That is, an API session created on one HMC of a primary/alternate HMC pair is not also available on the
alternate HMC of that pair. Nor will that session (and its associated session-id) be available on the other
HMC should a primary/alternate role switch occur due to a failure of the primary HMC. After a
primary/alternate role switch, client applications will need to establish new sessions by making Logon
requests again.

Sessions are identified by clients using a session-id, which is a string of up to 64 characters in length that
is returned to the client in the results from a successful Logon operation. This string is generated in a
cryptographically-secure manner. A session-id string is a form of authentication credentials for a user
equivalent in power to a user's user ID and password. Because of this, a session-id should be transmitted
only within SSL connections.

In order to indicate that subsequent requests are to be performed in the context of a designated session,
the client supplies the appropriate session-id to the HMC in each such subsequent request. This is done
by supplying the session-id as the value of the X-API-Session HTTP header which is an
application-specific header defined by and recognized by the HMC.

The Logon and Query API Version operations are the only two operations in the Web Services API that
can be performed without an API session so requests for these operations do not need to provide the
X-API-Session HTTP header. All other operations are valid only in the context of an API session and thus
requests for all other operations must supply an X-API-Session header with a valid session-id in order to
be successfully executed.

Query API Version

The Query API Version operation returns information about the level of Web Services API supported by
the HMC.

HTTP method and URI

GET /api/version

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description

api-major-version Integer The major-version part of the API version in effect for this session
api-minor-version Integer The minor-version part of the API version in effect for this session
hmc-version String (5-8) The version number of the HMC firmware. This is a string of the form v.r.m,
where each of v, r and m can be one or two digits. Example: "2.11.1".
hmc-name String (1-16) The name assigned to the HMC
hmc-time Timestamp The current time, according to the HMC.
classification-text String (0-50) The HMC's classification text. A 0-length string or null is returned if the
classification is not set. If the classification text is more than 50 characters,
only the first 50 are returned.

68 HMC Web Services API

 Level 04a

Field name Type Description

| vendor String The vendor that supplied the HMC. Non-IBM vendors are identified in an
| Enum abstract fashion rather than by company name. The valid values are:
| v "ibm" - IBM
| v "a" - vendor a
| v "b" - vendor b
| v "c" - vendor c

Description
This operation returns name and version information for the HMC and the HMC API.

This operation can be requested without an API session being open, i.e. no X-API-Session header, and
session-id is required on input.

This operation can be invoked on the alternate HMC.

For more information about the function included in each API version, see “Summary of API version
updates” on page 7.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 68.

Under normal conditions, no error response codes are returned by this request. (HTTP Status code 500
could possibly result if internal HMC errors occur.)

Example HTTP interaction

Request:

GET /api/version HTTP/1.1

Response:

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 07 Aug 2018 20:02:57 GMT
content-type: application/json;charset=UTF-8
| content-length: 167
{
"api-major-version":2,
"api-minor-version":20,
"classification-text":"Top Secret",
"hmc-name":"HMCTR117",
"hmc-time":1504814577975,
"hmc-version":"2.14.0",
| "vendor":"ibm"
}

Chapter 7. General API services 69

 Level 04a

Logon
The Logon operation establishes an API session with the Web Services API.

HTTP method and URI

POST /api/sessions

Request body contents

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

Field name Type Rqd/Opt Description

userid String Required The name of the HMC user to be associated with the new API
session. This name may be of arbitrary length, i.e. the HMC
does not have a defined maximum length.
password String Required The password used to authenticate the HMC user identified
by the userid field. The required length and valid characters
are determined by the password policy in effect for the user
ID.
new-password String Optional A new password to be established for the user defined by the
userid field. The required length and valid characters are
determined by the password policy in effect for the user ID.
multi-factor- String User- The current multi-factor authentication code (time-based
authentication-code (1-12) dependent one-time password) used to authenticate the HMC user
identified by the userid field. This field is required for HMC
users that are configured to use multi-factor authentication
and must be omitted for all other HMC users.
client-tag String Optional A tag string supplied by the API client program that issued
Enum the Logon request. Valid values are:
v "mobile" - the client asserts that it is the mobile app. This
value is intended for use only by the Mobile HMC app.
The last logon time for each user of this client tag is
displayed in the HMC Mobile Settings task.

The largest request body accepted by this operation is 512 bytes. Requests with bodies that exceed this
maximum are rejected with an HTTP status 413 (Request Entity Too Large) response.

Response body contents

On successful completion, the response body contains a JSON object with the following fields:

Field name Type Description

api-session String (1-64) The session-id of the newly created session. The client must specify this
value in the X-API-Session header of all subsequent requests that are to be
performed in the session.
notification-topic String The name of the JMS topic the HMC will use to send object-related
(1-128) notification messages to this session.
job-notification- String The name of the JMS topic the HMC will use to send job-related notification
topic (1-128) messages to this session.
api-major-version Integer The major-version part of the API version in effect for this session
api-minor-version Integer The minor-version part of the API version in effect for this session

70 HMC Web Services API

 Level 04a

Field name Type Description

password-expires Integer The time interval, in days, until the user's current password expires. A value
of 0 indicates that the password will expire within the next 24 hours. A
value of -1 indicates that the HMC does not enforce password expiration for
this user, however, if this user is authenticated with an external
authentication mechanism (e.g. LDAP) such expiration might be enforced by
that mechanism.
shared-secret-key String (32) The proposed shared secret key for the user identified in the request body.
This field is only included if the user is required to establish a shared secret
key; in that case, the Logon operation completes with HTTP status code 201
(Created).
session-credential String (32) The session-specific authentication credential for this session. This token can
be used to connect to the API message broker on behalf of the HMC user
associated with this session. See “Connecting to the API message broker” on
page 47 for more information.

Description
This operation opens a new API session with the Web Services API. Authentication is performed as part
of this process.

The characteristics and permissions of an HMC user are specified in an HMC User or User Template
definition. The user name provided in the userid field of the request body is used to select a
corresponding User or User Template based on the name. If such a User or User Template is found, the
client's authority to operate as this HMC user is authenticated by validating the password provided in
the password field using the authentication method specified in the User or User Template.

If the HMC user is configured for multi-factor authentication, additional authentication processing is
required. If the HMC user currently has an established shared secret key, the user's current multi-factor
authentication code provided in the multi-factor-authentication-code field is validated. If the HMC user
does not currently have an established shared secret key, HTTP status code 201 (Created) is returned.

If the authentication described above is successful, a new API session is created and the session-id for the
new session is provided in the api-session field in the response from this operation. This same value is
also provided by an X-API-Session HTTP header field in the response. If all required authentication is
successful, the newly created API session is fully authenticated. If HTTP status code 201 (Created) is to be
returned, a partially-authenticated API session is created. In this case an Establish Shared Secret Key
operation, using the key supplied in the shared-secret-key field in the response body, must be issued to
establish a shared secret key and complete the API logon sequence, thereby converting the
partially-authenticated session into a fully-authenticated session. The operations available to a
partially-authenticated session are limited to the Establish Shared Secret Key and Logoff operations.

If the request specifies an X-API-Session HTTP header field on input (indicating that this operation be
performed under some designated session), the logon request fails and status code 400 (Bad Request) is
returned.

If an HMC User or User Template corresponding to the user ID field does not exist, or if the password or
multi-factor authentication code validation fails, the logon request fails and status code 403 (Forbidden) is
returned. There is no reason code to distinguish these reasons for the failure. If the User or User Template
is marked as disabled or the associated password has expired, or if the User or User Template is not
configured to allow use of the API, the login request also fails with status code 403 (Forbidden) and a
reason code identifying the specific cause.

If all required user authentication is successful and the request body contains the optional new-password
field, the password associated with the user is changed to the specified new value as part of the Logon

Chapter 7. General API services 71

 Level 04a

operation. If the new password does not meet the requirements of the password policy in effect for this
user or if the password is not changeable because it is managed by an external authentication
mechanism, the request fails with status code 400 (Bad Request) and a reason code indicating the cause of
the failure.

As part of establishing the new API session, names are assigned for the JMS topics that will be used by
the HMC to send object-related and job-related notification messages to this session and the names of
these topics are provided in fields of the response body. The name of the topic used for object-related
notifications is provided in the notification-topic field of the response, and the name of the topic used for
job-related notifications is provided in the job-notification-topic field.

This operation can be invoked on the alternate HMC, however password changes cannot be requested
(i.e. the new-password field cannot be provided) in this case.

Authorization requirements
This operation has the following authorization requirement:
v The HMC User Profile or User Template selected by the userid field must be configured to allow use
of the Web Services API.

HTTP status and reason codes

On success, HTTP status code 200 (OK) or 201 (Created) is returned and the response body is provided as
described in “Response body contents” on page 70.

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

72 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
12 The request specified an X-API-Session header, which is interpreted as an
attempt to unnecessarily logon again when already logged on.
13 The maximum number of logged in user sessions for this user ID has been
reached; no more are allowed.
42 Password changes cannot be requested when logging on to the alternate
HMC.
43 The password for this user cannot be changed, for example because it is
managed in an external authentication mechanism such as LDAP.
44 The new password does not conform to the requirements of the password
policy in effect for this user.
45 The user's password has expired and no new-password field was specified.
46 The user must establish a shared secret key prior to changing the logon
password via the new-password field in the request body.
47 The user is required to include a multi-factor authentication code during
logon but the request body did not include the multi-factor-authentication-
code field.
48 The user is not required to include a multi-factor authentication code but the
multi-factor-authentication-code field was included in the request body.
49 The specified multi-factor authentication code is correct, but it has already
been used. A code may only be used once. Wait until a new code is available
and try again.
403 (Forbidden) 0 User authentication failed.
40 The user is disabled.
41 The user is not authorized to use the HMC Web Services interface.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Usage notes
v The Logon operation checks for and prevents requests that specify an X-API-Session header on input
in order to detect client applications that unnecessarily log on again when already logged on. It is valid
to have multiple sessions, but in order to more explicitly indicate that this is desired, the client
application needs to request each logon without referencing any existing session.
v Some of the information returned by this operation is also present in the response body of a successful
Get Notification Topics request. Specifically, the information contained in the notification-topic and
job-notification-topic fields is also included in the Get Notification Topics response. That operation
identifies all JMS topics available to the API user, possibly including topics other than those identified
in the Logon response.
v The multi-factor authentication code is a time-based one-time password as defined in RFC 6238, TOTP:
Time-Based One-Time Password Algorithm, May 2011, (available at: https://tools.ietf.org/html/rfc6238
from the Internet Engineering Task Force. The TOTP algorithm uses a shared secret key and the current
time of day to calculate the TOTP for the current 30-second interval.
v When using multi-factor authentication the user must establish a shared secret key. This key is
sensitive security information much like a password and is to be known only by the user and the
HMC. This key can be established via the Establish Shared Secret Key operation or by logging on to

Chapter 7. General API services 73

 Level 04a

the HMC via the local GUI interface or a remote web browser. The HMC presents this key to the user
only once (during the first logon after being required to use multi-factor-authentication or having their
shared secret key be invalidated by an administrator), and it is the user's responsibility to have it
available for use during subsequent API and GUI logons, which will require the user's current
multi-factor authentication code.
v The sequence of operations to establish a shared secret key via the APIs is as follows:
– Issue a Logon operation with a valid logon password.
– The Logon completes with HTTP status code 201 (Created) and returns an API session ID for a
partially-authenticated session and a proposed shared secret key.
– Issue an Establish Shared Secret Key operation with the API session ID and calculated multi-factor
authentication code.
– The Establish Shared Secret Key operation completes with HTTP status code 204 (No Content), the
partially-authenticated session is converted into a fully-authenticated session and the proposed key
is now the user's officially established shared secret key.
v When using multi-factor authentication it is important for the API client's time of day clock to be
reasonably in sync with the HMC's clock, because the current time of day is used when calculating the
user's current multi-factor authentication code. To determine if the clocks are reasonably in sync, the
Query API Version operation may be used to obtain the HMC's current time, which can then be
compared to that of the API client.
v If an Establish Shared Secret Key operation is required to complete a logon sequence that includes a
client-tag field, the last mobile app logon time for the API user is not updated until the Establish
Shared Secret Key operation completes successfully.

Example HTTP interaction

POST /api/session HTTP/1.1

content-type: application/json
content-length: 58
{
"password": "12345678",
"userid": "APIUSER"
}

Figure 1. Logon: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 02 Aug 2017 18:41:27 GMT
x-api-session: 4hy7c4nogldz4b59ajegzb1dulec641ziyv6uf73zs43205edv
content-type: application/json;charset=UTF-8
content-length: 281
{
"api-major-version": 20,
"api-minor-version": 2,
"api-session": "4hy7c4nogldz4b59ajegzb1dulec641ziyv6uf73zs43205edv",
"job-notification-topic": "APIUSER.229job",
"notification-topic": "APIUSER.229",
"password-expires": 29,
"session-credential": "un8bu462g37aw9j0o8pltontz3szt35jh4b1qe2toxt6fkhl4"
}

Figure 2. Logon: Response

74 HMC Web Services API

 Level 04a

Establish Shared Secret Key

The Establish Shared Secret Key operation completes the authentication of a partially-authenticated API
session and establishes the user's multi-factor authentication shared secret key.

HTTP method and URI

POST /api/sessions/operations/establish-shared-secret-key

Request body contents

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

Field name Type Rqd/Opt Description

multi-factor- String Required The current multi-factor authentication code (time-based
authentication-code (1-12) one-time password) to be used to authenticate the HMC user
associated with the partially-authenticated API session
specified on the X-API-Session request header.

Description
This operation establishes a shared secret key for a user that is configured for multi-factor authentication.
It completes the authentication of a partially-authenticated API session created by a previous Logon
operation that completed with HTTP status code 201 (Created). That API session's ID must be specified
on the X-API-Session request header. The request body must contain the current multi-factor
authentication code calculated using the proposed shared secret key returned in the response body of the
aforementioned Logon operation.

If the X-API-Session request header does not identify a partially-authenticated session, HTTP status code
400 (Bad Request) is returned. If the multi-factor authentication code is not correct for the proposed
shared secret key and current time of day, HTTP status code 403 (Forbidden) is returned. If the
requirement for the user to establish a shared secret key no longer exists, HTTP status code 409 (Conflict)
is returned with a reason code that indicates what has changed.

If the operation fails for any reason, the partially-authenticated session is destroyed.

Authorization requirements
This operation has no explicit authorization requirements; however, the request must contain the session
ID of the partially-authenticated API session and the current multi-factor authentication code for that
session.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden) 0 The multi-factor authentication code is not valid for the API session
identified by the X-API-Session request header.

Chapter 7. General API services 75

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict 12 The user associated with the API session identified by the X-API-Session
request header already has an established shared secret key. That key could
have been established by another API session or a GUI logon.
13 The user associated with the API session identified by the X-API-Session
request header is no longer configured for multi-factor authentication.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Usage notes
See the usage notes for the Logon operation for more information on using multi-factor authentication
with the APIs.

Example HTTP interaction

POST /api/sessions/operations/establish-shared-secret-key HTTP/1.1

x-api-session: 5ql67thiw2og8ysixzljv8pwwmb4exfp85h9lu23a2irjxaq0w
content-type: application/json
content-length: 46
{
"multi-factor-authentication-code":"314159"
}

Figure 3. Establish Shared Secret Key: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 16 Dec 2016 21:21:09 GMT

<No response body>

Figure 4. Establish Shared Secret Key: Response

Logoff
The Logoff operation closes an API session with the Web Services API.

HTTP method and URI

DELETE /api/sessions/this-session

Description
This operation closes an API session with the Web Services API.

The session to be closed is indicated by the session-id in the X-API-Session header of the request. If the
session-id designates an open session, the API session is closed and status code 204 (No Content) is
returned. Closing of the API session includes closing/deleting any Metrics Service retrieval contexts or
JMS notification topics associated with the session. However, asynchronous actions initiated by the
session continue to run.

76 HMC Web Services API

 Level 04a

Once a session is closed, its session-id is no longer valid for use in subsequent Web Services API
requests. Attempts to do so will result in the same errors as any other attempt to use a session-requiring
operation without providing a valid session-id.

This operation can be invoked on the alternate HMC.

Authorization requirements
This operation has the following authorization requirement:
v No explicit authorization is required, however the client application must possess and present a valid
session-id of the session to be closed.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned with no response body.

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

DELETE /api/session/this-session HTTP/1.1

x-api-session: zkspmapxgtcasy5uixmtwuaudqe8ha6fy0006bzmxsm2bd8yo

Figure 5. Logoff: Request

204 No Content
date: Wed, 20 Jul 2011 18:33:56 GMT
x-request-id: Sx32 Rx0
server: zSeries management console API web server / 1.0
cache-control: no-cache

Figure 6. Logoff: Response

Get Notification Topics

The Get Notification Topics operation returns a structure that describes the JMS notification topics
associated with the API session. These topics allow the user to receive various types of asynchronous
notifications from the HMC.

HTTP method and URI

GET /api/sessions/operations/get-notification-topics

Chapter 7. General API services 77

 Level 04a

Response body contents

On successful completion, the response body is a JSON object with the following field:

Field name Type Description

topics Array of Array of nested topic-info objects as described in the next table
objects

Each nested topic-info object contains the following fields:

Table 22. topic-info object
Field name Type Description
topic-type String
Enum The type of notification topic, which provides an indication of the type of
data found on the topic. Except for os-message-notification, a given value
will only be represented at most once within a single response. One of the
following values:
v "object-notification" - The object notification topic. This topic is consistent
with the information returned in the notification-topic field in the
response body of a successful Logon request. It is used by the HMC to
send object-related notifications to this session.
v "job-notification"- The job notification topic. This topic is consistent with
the information returned in the job-notification-topic field in the response
body of a successful Logon request. It is used by the HMC to send
job-related notifications to this session.
v "audit-notification" - the audit notification topic. This topic is used by the
HMC to send audit-related events to this session.
v "security-notification" - the security notification topic. This topic is used
by the HMC to send security-related events to this session.
v "os-message-notification" - an operating system message notification
topic. Topics of this type are used by the HMC to send notifications that
pertain to new or refreshed messages generated by the operating system
running in a partition. More than one of these might exist for this session.
Additional fields specific to this topic type are described later in this table.
topic-name String The name of the notification topic. API users can connect using this name to
(1-128) receive notifications for the topic.
object-uri String/URI When the topic-type is "os-message-notification", this field is the canonical
URI path of the partition object for which this topic exists.

This field does not exist for the other topic types.
include-refresh- Boolean When the topic-type is "os-message-notification", this field indicates
messages whether refresh operating system messages will be sent on this topic. A
value of true indicates that refresh messages will be sent. A value of false
indicates that no refresh messages will be sent.

This field does not exist for the other topic types.

Description
This operation returns a list of all JMS topics to which the API user is authorized to connect. As there
exists at least one JMS topic available to any authenticated user, the returned JSON array will never be
empty.

Authorization Requirement
This operation has the following authorization requirement:

78 HMC Web Services API

 Level 04a

v No explicit authorization is required; however, the response to this request is limited to the topics to
which the user is authorized to connect.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 78.

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

GET /api/sessions/operations/get-notification-topics HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k

Figure 7. Get Notification Topics: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Sat, 14 Sept 2013 18:03:00 GMT
content-type: application/json;charset=UTF-8
{ “topics” :
[
{ “topic-type”:”object-notification”, “topic-name”:”mikeuser.1” },
{ “topic-type”:”job-notification”, “topic-name”:”mikeuser.1job” },
{ “topic-type”:”audit-notification”, “topic-name”:”mikeuser.1aud” },
{ “topic-type”:”security-notification”, “topic-name”:”mikeuser.1sec” }
{ “topic-type”: “os-message-notification”,
“topic-name”: “mikeuser.1osmsg.cpc1.lpar1”,
“object-uri”: “/api/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9”,
“include-refresh-messages”: true },
{ “topic-type”: “os-message-notification”,
“topic-name”: “mikeuser.1osmsg.cpc2.par7”,
“object-uri”: “/api/partitions/458e44e1-b0c2-391b-83ff-ecfd847295bd”,
“include-refresh-messages”: false }
]
}

Figure 8. Get Notification Topics: Response

Usage notes
Some of the information returned by this operation is also present in the response body of a successful
Logon request. This operation is intended to provide a superset and will contain all JMS topics available
to the API user including the two topics indicated in the Logon response.

Chapter 7. General API services 79

 Level 04a

Asynchronous job processing

Some of the operations that are provided in the Web Services API may take a significant amount of
elapsed time to complete. In order to optimize the usage of HMC session resources and to allow the
client application the opportunity to perform other processing, such long-running operations are
structured to be executed asynchronously (rather than synchronously) from the perspective of the client
application.

In a synchronous operation, the Web Services API does not respond to the client application's request
until all of the processing associated with the request is complete (successfully or in error) and the API
can provide a final result status for the operation. The client application thread is typically blocked (not
running) during this time.

By contrast, in a function that operates asynchronously by starting a job, the Web Services API performs
just the minimal front-end validation and set up work needed to accept the request to perform the
indicated operation, and then quickly returns an HTTP 202 (Accepted) result to the client indicating that
the operation request has been started but is not yet finished. Along with the HTTP 202 (Accepted) result,
the client application is provided with a URI that represents the asynchronous job that is in progress. This
URI is of the form /api/jobs/{job-id}.

At any point after receiving the HTTP 202 (Accepted) result, the client application can invoke the Query
Job Status operation described in this section to determine if the job has ended or not. A job is
considered ended if it runs to completion or is canceled. If the job has not yet ended, the Query Job
Status request returns an indication that the job is still running or cancellation has been requested. If the
job has ended, the Query Job Status request returns an indication of how the job ended along with the
final status code, reason code and result data associated with the now-finished asynchronous processing.
Once a job ends, job status is retained by the HMC for a minimum of 4 hours to allow the client
application time to retrieve the results, but this status and results are not held indefinitely.

Since the major reason an API operation is structured to be asynchronous is that it will take significant
time to complete, very frequent polling for completion via calls to Query Job Status can lead to
significant unproductive use of client application and HMC resources. In order to eliminate the need to
poll at all, the Web Services API also provides asynchronous notifications of job completion or
cancellation via its JMS notification capability. IBM recommends that client applications use this
notification facility to determine when a job has ended rather than polling. See “Job completion
notification” on page 54 for details on this notification mechanism.

If it is not practical for a client application to use asynchronous notification of job completion, the
application should introduce elapsed-time delays between successive Query Job Status requests to poll
the current job status in order to reduce unproductive use of resources.

Query Job Status

The Query Job Status operation returns the status associated with an asynchronous job.

HTTP method and URI

GET /api/jobs/{job-id}

In this request, the URI variable {job-id} is the identifier of an asynchronous job associated with the API
user, as returned in the response of the operation that initiated the job.

80 HMC Web Services API

 Level 04a

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description

status String An indication of the current disposition of the job. The possible values are as
Enum follows:
v "running" - indicates that the job was found and it has not ended at the
time of the query.
v "cancel-pending" - indicates that the job was found and it has not ended
but cancellation has been requested.
v "canceled" - indicates that the job's normal course of execution was
interrupted by a cancel request.
The successful or unsuccessful completion of the job is indicated by the
job-status-code and job-reason-code fields.
v "complete" - indicates that the job was found and has completed running.
The successful or error completion of the job is indicated by the
job-status-code and job-reason-code fields.
job-status-code Integer; The job completion status code. This field is provided only if the status field
Field is set to "complete" or "canceled".
provided
only if This field provides the major status code describing the success or failure
status is completion of the asynchronous action represented by the job. It is expressed
"complete" in terms of an HTTP status code (i.e. the HTTP status code that would have
or been returned for the operation had it been performed synchronously).
"canceled"
The values provided here and their meaning depend on the particular action
that is being performed asynchronously. The description of these values is
provided as part of the description for the operation that initiated the
asynchronous job.
job-reason-code Integer; The job completion reason code. This field is provided only if the status field
Field is set to "complete" or "canceled" and only if the job-status-code field
provided indicates an error completion (status code other than 2XX).
only if
status is When present, this field provides a more detailed reason code describing the
"complete" success or failure completion of the asynchronous action represented by the
or job. It is expressed in terms of the API reason code as are returned in
"canceled" standard error response bodies provided by the API.

The values provided here and their meaning depend on the particular action
that is being performed asynchronously. The description of these values is
provided as part of the description or the operation that initiated the
asynchronous job.
job-results Object; A nested object that provides results for the job
Field
provided This file is provided only if the status field is set to "complete" or "canceled"
only if and the asynchronous operation is documented to provide job results. If the
status is status field is set to some other value, or the asynchronous operation
"complete" provides no result information (beyond the job status and reason codes) then
or this field is omitted.
"canceled"
The structure of the nested object provided by this field and its meaning
depends on the particular action that is being performed asynchronously.
The description of this object's structure is provided as part of the
description of the operation that initiated the asynchronous job.

Chapter 7. General API services 81

 Level 04a

Description
The Query Job Status operation returns the status associated with an asynchronous job.

If the job designated by the URI is still running, the operation sets the status field in the response body
to "running" and provides no other information about the job. If cancellation has been requested for the
job designated by the URI but the cancellation action has not yet caused the job to end, the operation sets
the status field in the response body to "cancel-pending" and provides no other information about the
job. The client application may repeat the query at a later time, but should avoid frequent polling since
that can lead to unproductive use of client and HMC resources. In order to eliminate the need to poll at
all, the client application can (and should) use the asynchronous notifications facility provided by the API
to receive notification that the job has ended via a JMS-based message. See “Job completion notification”
on page 54 for details on this notification mechanism.

If the job is complete, the operation sets the status field in the response body to "complete" and provides
the other completion-related fields defined in the response body contents section above to report the
results to the client application. If the job's normal execution sequence was interrupted by a cancel action,
the operation sets the status field in the response body to "canceled" and provides the other related fields
defined in the “Response body contents” on page 81 to report the results to the client application. Once a
job ends, job status is retained by the HMC for a minimum of 4 hours to allow the client application time
to retrieve the results, but this status and results are not held indefinitely.

If the URI does not designate a job associated with the API user, HTTP status code 404 (Not Found) is
returned to the client.

Authorization requirements
This operation has the following authorization requirement:
v The job URI must designated an asynchronous job associated with the API user.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 81.

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The URI does not designate an asynchronous job associated with the API
user.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

82 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/jobs/86e44546-107f-11e1-bde0-0010184c8334 HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4rymqa8ktzjep7dbyrll0k

Figure 9. Query Job Status: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 16 Nov 2011 18:19:35 GMT
content-type: application/json;charset=UTF-8
content-length: 63
{
"job-reason-code": 0,
"job-status-code": 200,
"status": "complete"
}

Figure 10. Query Job Status: Response

Delete Completed Job Status

The Delete Completed Job Status operation deletes the job status and results associated with a job that
has ended.

HTTP method and URI

DELETE /api/jobs/{job-id}

In this request, the URI variable {job-id} is the identifier of an asynchronous job associated with the API
user, as provided by the operation that initiated the job.

Description
The Delete Completed Job Status operation deletes the job status and results associated with a job that
has ended.

If the job designated by the request URI has completed or has been canceled, its ending status and results
are deleted from the HMC and status code 204 (No Content) is returned to the client.

If the job has not yet ended (i.e. is still running, or cancellation has been requested but is still pending),
the operation fails and HTTP status code 409 (Conflict) is returned to the client.

If the URI does not designate a job associated with the API user, or if the job's status has already been
deleted (either explicitly, or due to expiration of the status retention interval), HTTP status code 404 (Not
Found) is returned to the client.

Authorization requirements
This operation has the following authorization requirement:
v The job URI must designate an asynchronous job associated with the API user.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

Chapter 7. General API services 83

 Level 04a

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The URI does not designate an asynchronous job associate with the API user.
409 (Conflict) 40 The URI designates an asynchronous job that has not ended.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Usage notes
v This operation is defined to operate only on jobs that have ended, i.e. have a status field with value
"complete" or "canceled". As a result, this operation cannot be used to cancel an in-progress
asynchronous operation. See “Cancel Job” for information pertaining to job cancellation.
v Once an asynchronous job has ended, job status is retained by the HMC for a minimum of 4 hours to
allow the client application time to retrieve the results, but this status and results are not held
indefinitely. At the expiration of the retention interval, job status is deleted as if the Delete Completed
Job Status operation were called.

Example HTTP interaction

DELETE /api/jobs/86e44546-107f-11e1-bde0-0010184c8334 HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4rymqa8ktzjep7dbyrll0k

Figure 11. Delete Completed Job Status: Request

204 No Content
date: Wed, 16 Nov 2011 18:19:35 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 12. Delete Completed Job Status: Response

Cancel Job
The Cancel Job operation attempts to cancel an asynchronous job.

HTTP method and URI

POST /api/jobs/{job-id}/operations/cancel

In this request, the URI variable {job-id} is the identifier of an asynchronous job associated with the API
user, as provided by the operation that initiated the job.

84 HMC Web Services API

 Level 04a

Description
The Cancel Job operation attempts to cancel the specified job. The specific nature of the asynchronous job
and its current state of execution when the request is received can affect the success of the cancellation
action.

Not all asynchronous jobs support job cancellation. If a particular type of job supports cancellation, the
description of the operation that initiates that type of job will explicitly specify that cancellation is
supported and may describe other cancellation characteristics as well. If the description of the operation
that initiates that type of job does not specify that cancellation is supported, then cancellation of that type
of job is not possible.

If the specified job exists, but is of a type that does not support cancellation, status code 404 (Not Found)
is returned and the job is allowed to continue processing without interruption.

If the specified job exists and has not yet completed (that is, the value of its status property is "running"),
the cancellation request is made pending for the job, the status of the job is changed to "cancel-pending",
and HTTP status code 202 (Accepted) is returned. The processing of the pending cancellation request
occurs asynchronously to the completion of the Cancel Job operation.

If the specified job exists and supports cancellation but either already has a cancellation request pending
or has already ended (that is, has a status property with values "cancel-pending", "complete" or
"canceled"), HTTP status code 409 (Conflict) is returned with a reason code that more specifically
indicates the particular error condition.

Once a cancellation request is made pending, the HMC will take steps to interrupt the processing of the
job in order to cause the processing to end as quickly as is possible considering the nature of the
processing done by the job. The conditions under which a running job can be interrupted vary depending
on the type of job. For some types of jobs the console may be able to interrupt the processing very
quickly while for others the console may be able to do so only as processing crosses selected interruption
points. Thus, acceptance of a cancellation request does not guarantee that the processing of the job will
either be immediately or eventually interrupted. As a consequence, it is possible that a job may proceed
to normal completion (end with a status of "complete") even after a cancellation request was accepted for
the job.

Authorization requirements
This operation has the following authorization requirement:
v The job URI must designate an asynchronous job associated with the API user.

HTTP status and reason codes

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The URI does not designate an asynchronous job associated with the API
user.
4 The URI designated an asynchronous job that can not be canceled.

Chapter 7. General API services 85

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 41 The URI designates an asynchronous job that has ended. It can not be
canceled.
42 The URI designates an asynchronous job that already has a cancellation
request pending. A second cancel request is not allowed.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

POST /api/jobs/86e44546-107f-11e1-bde0-0010184c8334/operations/cancel HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4rymqa8ktzjep7dbyrll0k

Figure 13. Cancel Job: Request

202 Accepted
date: Wed, 10 June 2015 18:19:35 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache
<No response body>

Figure 14. Cancel Job: Response

86 HMC Web Services API

 Level 04a

Chapter 8. Inventory and metrics services

The functions described in this chapter are termed “services” because unlike the interfaces described in
many of the other chapters of this document, the functions described here are service-oriented rather than
object-oriented in nature. That is, the functions of these services operate across multiple instances of
managed objects rather than being directed at particular managed object instances.

The Inventory Service provides an efficient mechanism for retrieving identify and configuration
information about all of the manageable resource instances that are managed by zManager. It provides
this information in bulk form via a single request, and thus is expected to be a much more efficient
means of determining this information than walking the entire resource tree one object at a time. It is
anticipated that this service supports the requirements of a “discovery” phase of a client application that
is interested in configuration information about all resources managed by zManager.

The Metrics Service provides a mechanism to retrieve performance metric data for resources that are
managed by zManager. This data is captured periodically and buffered on the HMC. The data may
include snapshots of performance data at a moment in time, or accumulated performance data, or both,
as appropriate. This service is designed to support client applications that provide monitoring function
for zManager managed resources.

Inventory services operations summary

The following operation is provided by the Inventory service:
Table 23. Inventory service: operations summary
Operation name HTTP method and URI path
“Get Inventory” on page 88 POST /api/services/inventory

Metrics service operations summary

The following operations are provided by the Metrics service:
Table 24. Metrics service: operations summary
Operation name HTTP method and URI path
“Create Metrics Context” POST /api/services/metrics/context
on page 94
“Get Metrics” on page 97 GET /api/services/metrics/context/{metrics-context-id}
“Delete Metrics Context” DELETE /api/services/metrics/context/{metrics-context-id}
on page 101

Table 25. Metrics service: URI variables

Variable Description
{metrics-context-id} Identifier of a metrics context object. Metrics contexts are associated with API sessions.
Thus, this identifier is assigned by the metrics service so that it is unique within an API
session and has a lifetime scoped to that session.

© Copyright IBM Corp. 2017, 2018 87

 Level 04a

Inventory service
The Inventory Service is an API which allows the client application to fetch a list of ensemble resources
and their properties.

This service is intended to support clients that need to determine the inventory and properties of all of
the resources of the ensemble (or at least a large portion of those resources). Retrieving this information
in bulk form using this service is expected to be much more efficient than walking the resource tree one
object at a time using the object-oriented operations of the Web Services API.

The ability to filter the results to only certain classes of resources is provided.

A response to an inventory request is a series of JSON objects returned using HTTP chunked transfer
encoding. These objects will be in a format specified in the corresponding resource class's inventory
service data sections.

Resources returned are those to which the API client has object-level authorization.

Get Inventory
The Get Inventory operation fetches ensemble resources and associated properties.

HTTP method and URI

POST /api/services/inventory

Request body contents

The request body can include a specification of the classes of resources that should be returned. It
contains the following field:

88 HMC Web Services API

 Level 04a

Field name Type Description

resources Array of An array of String values. Each element specifies a category or class of
String resource that should be returned. A category is simply a grouping of classes,
Enum so specifying a category is functionally equivalent to specifying all of its
member classes. The request may include both categories and classes.

Omitting the resources field, or providing an empty array, is equivalent to

specifying an array listing all of the supported classes.

Categories and associated class values:

v Category: "zvm-resources"
– Class: "zvm-virtualization-host"
– Class: "zvm-virtual-server"
v Category: "power-vm-resources"
– Class: "power-vm-virtualization-host"
– Class: "power-vm-virtual-server"
v Category: "x-hyp-resources"
– Class: "x-hyp-virtualization-host"
– Class: "x-hyp-virtual-server"
v Category: "prsm-resources"
– Class: "prsm-virtualization-host"
– Class: "prsm-virtual-server"
v Category: "dpm-resources"
– Class: "adapter"
– Class: "partition"
– Class: "virtual-switch"
| – Class: "storage-site"
| – Class: "storage-fabric"
| – Class: "storage-switch"
| – Class: "storage-subsystem"
| – Class: "storage-control-unit"
| – Class: "storage-group"
v Category: "virtual-server-common"
– Class: "power-vm-virtual-server-common"
– Class: "prsm-virtual-server-common"
– Class: "x-hyp-virtual-server-common"
– Class: "zvm-virtual-server-common"
v Category: "zbx-resources"
– Class: "zbx"
– Class: "rack"
– Class: "power-blade"
– Class: "system-x-blade"
– Class: "isaopt-blade"
– Class: "dpxi50z-blade"
– Class: "bladecenter"
v Category: "ensemble-wide-resources"
– Class: "ensemble"
– Class: "workload-resource-group"
– Class: "virtual-network"
– Class: "storage-resource"
v Category: "core-resources"
– Class: "cpc"
– Class: "logical-partition"
v Category: "console-resources"
– Class: "console"
– Class: "custom-group"
– Class: "user"
– Class: "user-role"

Chapter 8. Inventory and metrics services 89

 Level 04a

Field name Type Description

Notes:
v The various classes of virtual server, virtualization host, blade, and group above (for example,
"x-hyp-virtual-server", "prsm-virtualization-host", "power-blade", and "custom-group") are actually type-specific
variations of the object classes "virtual-server", "virtualization-host", "blade" and "group". They are specified
with type qualifiers in the names here to allow distinguishing these types on inventory queries. The objects
returned in the inventory response will be of the actual object classes ("virtual-server", "virtualization-host",
"blade" or "group"), and will have appropriate type values as defined in the data models for those classes.
v The various classes within the "virtual-server-common" category above represent inventory queries that return a
common subset of the virtual server’s properties rather than the entire set of properties defined in the data
model. They correspond to Get Virtual Server Properties requests with the properties=common query parameter
specified. Refer to the documentation for the Get Virtual Servers Properties operation and the discussion of
inventory service data for Virtual Server objects for specific information on the properties provided.

Response body contents

On successful completion, the response body is a JSON array of JSON objects sent using HTTP chunked
transfer encoding. The order in which these objects are returned is unspecified.

The array element documents are of 2 types:

v For resources that were successfully inventoried, the document will be as specified in the
corresponding resource's inventory service data.
v For resources that were found but not successfully fully inventoried (i.e. the Object URI can be
determined but not the properties), an inventory error document will be returned. Note that, even if
one or more of these inventory error documents is contained in the response, an HTTP status code of
200 (OK) is still returned. The fields in the inventory error document are:

Field name Type Description

uri String/URI Canonical URI of the resource which could not be fully inventoried.
class String The class for these error documents is "inventory-error".
inventory-error-code Integer A reason code for the inventory failure. Note that all of these reasons
indicate success in locating a resource, but some sort of failure in gathering
its properties during inventory collection. A subsequent call to get the
properties for the URI in this error document may succeed.
v 1: Resource not found on target. Although the resource's URI was located
on the HMC, its properties were subsequently not located on the HMC or
SE on which the property data for the managed object is to be gathered.
v 2: Communication problem. Communication problems were experienced
with the SE on which the property data for the managed object is to be
gathered.
v 3: Plugin load error. The code responsible for capturing the properties of a
resource class experienced an unexpected problem loading.
v 4: Unknown plugin error. The code responsible for capturing the
properties of a resource returned an unrecognized error.
v 5: Unexpected plugin error. The code responsible for capturing the
properties of a resource returned an unexpected error.
v 6: Timeout error. The code responsible for capturing the properties of a
resource did not respond within the time allocated to it.
inventory-error-text String An error description for the inventory failure.

90 HMC Web Services API

 Level 04a

Field name Type Description

inventory-error- inventory- A nested inventory-error-info object that provides additional diagnostic
details error-info information for unexpected inventory plugin errors. This field is provided if
Object the inventory-error-code field is 5 (indicating unexpected plugin error). It is
not provided for other inventory-error-code values. The format of the
inventory-error-info object is defined in the next table.

The inventory-error-info object contains the following fields:

Field name Type Description

http-status Integer HTTP status code for the request.
request-uri String The URI that caused this error response.
reason Integer Numeric reason code providing more details as to the nature of the error) than is
provided by the HTTP status code itself. This reason code is treated as a sub-code of
the HTTP status code and thus must be used in conjunction with the HTTP status
code to determine the error condition. Standard reason codes that apply across the
entire API are described in“Common request validation reason codes” on page 41.
Additional operation-specific reason codes may also be documented in the description
of the specific API operations.
message String Message describing the error. This message is not currently localized.
stack String Internal HMC diagnostic information for the error. This field is supplied only on
selected 5xx HTTP status codes.
error-details Object A nested object that provides additional operation-specific error information. This field
is provided by selected operations, and the format of the nested object is as described
by that operation.

Description
The Get Inventory operation returns information on ensemble resources and associated properties.

A resource is included in the response if it matches any one of the list of resource classes in the request
body. Specifying a category is equivalent to specifying its member classes. If a class is repeated on the
request, either explicitly or effectively via categories, the operation will behave as if the class were only
specified once. If no resources are specified in the request body, all resources are returned. The inclusion
of a resource may cause objects of certain related classes to also be included in the response. See the
resource's Inventory Service Data section for the information about which, if any, related classes will be
included.

Furthermore, a resource is included in the response only if the API user has object-access permission for
that resource. If an HMC is a manager of a resource but the API user does not have permission to it, that
resource is simply omitted from the response. A success status code is still returned.

If the HMC does not manage any resources to which the user has access, or if no resources are found that
match the request body specification, an empty response is returned with a 204 (No Content) status code.

In addition to objects for inventoried resources, the response may include objects for resources whose
URIs could be determined, but whose properties could not, for some reason, be obtained. Rather than
treat these resources as completely non-inventoried and omit them, the URI and an error reason are
returned.

The order in which the objects are returned is unspecified.

Chapter 8. Inventory and metrics services 91

 Level 04a

The Get Inventory implementation may choose to limit the number of simultaneous in-process inventory
requests. If such a limit is reached, further requests will return an HTTP 503 (Service Unavailable) error
status code until previous requests complete and the number of in-process inventory requests falls back
below the limit.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to any object to be included in the result.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 90. If there are no resources to provide, HTTP status code 204 (No
Content) is returned, along with an empty response body.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
503 (Service 200 The request could not be processed because of the number of currently
Unavailable) pending inventory requests. The request can be reissued at a later time.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Usage notes
The Get Inventory results represent a snapshot of inventory results as viewed from the HMC. The actual
inventory can change, even as the results are being streamed back to the API client. Therefore, if the
client wishes to stay informed about changes to the inventory and not risk missing any inventory
changes, it should use the API event mechanisms to subscribe to inventory-related events before even
issuing a Get Inventory request.

The Get Inventory results do not reflect all properties at a single moment in time. During the overall
inventory collection process multiple resource's states and other properties may change. Therefore, states
(or other properties) among two or more resources that might normally be expected to match (or have
some other expected relationship) at one moment in time may instead return apparently inconsistent
results in the Get Inventory response.

Example HTTP interaction

The following example illustrates a typical response for a Get Inventory request for the ensemble class of
resources. Responses for other classes will differ significantly from this because the data differs on a class
by class basis. The format of the data returned by the Inventory Service for each class of object is
described in a section entitled “Inventory service data” within the documentation for that object class.

92 HMC Web Services API

 Level 04a

POST /api/services/inventory HTTP/1.1

x-api-session: 38gu0i9so1y0vjemqyptpcadnwq0esu32pjd3ub4jy6lxadp72
content-type: application/json
content-length: 27
{
"resources": [
"ensemble"
]
}

Figure 15. Get Inventory: Request

200 OK
transfer-encoding: chunked
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 03:42:15 GMT
content-type: application/json;charset=UTF-8
[
{
"acceptable-status": [
"alternate-communicating"
],
"class": "ensemble",
"cpu-perf-mgmt-enabled-power-vm": false,
"cpu-perf-mgmt-enabled-zvm": false,
"description": "long ensemble name",
"has-unacceptable-status": false,
"is-locked": false,
"load-balancing-enabled": false,
"load-balancing-ip-addresses": [],
"load-balancing-port": 3860,
"mac-prefix": "02:00:00:00:00:00",
"management-enablement-level": "automate",
"name": "HMC_R74_ENSEMBLE",
"object-id": "1f7ffb02-de39-11e0-88bd-00215e67351a",
"object-uri": "/api/ensembles/1f7ffb02-de39-11e0-88bd-00215e67351a",
"parent": null,
"power-consumption": 24474,
"power-rating": 65644,
"reserved-mac-address-prefixes": [],
"status": "alternate-communicating",
"unique-local-unified-prefix": "fd2c:34be:df2:0:0:0:0:0"
},
{
"class": "node",
"element-uri": "/api/ensembles/1f7ffb02-de39-11e0-88bd-00215e67351a/nodes/
9ba3b1aa-693a-3408-80ae-9d0808147ffa",
"member": "/api/cpcs/9ba3b1aa-693a-3408-80ae-9d0808147ffa",
"parent": "/api/ensembles/1f7ffb02-de39-11e0-88bd-00215e67351a",
"type": "cpc"
}
]

Figure 16. Get Inventory: Response

Chapter 8. Inventory and metrics services 93

 Level 04a

Metrics service
The zEnterprise (or later) Ensembles, Central Processing Complexes (CPCs), and their associated system
resources are instrumented at key points to collect performance and utilization data. The data is
forwarded by the metric data providers to a buffer on the HMC where it is made available to consumers
of this API.

The data collection instrumentation organizes and formalizes the data it collects into a series of named
metric groups. The Metrics Service API allows specification of the metric groups the client wishes to
query. The API returns some information about the format of the metrics that are being fetched.
Specifically, a structure called a metrics context is associated with any metrics retrieval, and that structure
includes metric group names, individual metric field names, and the associated individual metric data
types.

The full metric group documentation, however, including descriptions of the data collected and the
frequency of collection, can be found in Chapter 9, “Metric groups,” on page 103.

Create Metrics Context

The Create Metrics Context operation creates a context under which metrics can be repeatedly retrieved.
This context will be associated with the API session under which it was created.

HTTP method and URI

POST /api/services/metrics/context

Request body contents

A request body must be specified. It has the following fields:

Field name Type Description

anticipated- Integer The number of seconds the client anticipates will elapse between Get
frequency-seconds Metrics calls against this context. The minimum accepted value is 15.
metric-groups Array of Optional. Array of metric group names. If specified, then results from future
Strings Get Metrics requests associated with this context will be limited to only
metrics with group names matching one of the specified values. If not
specified, or if an empty array is specified, then results will not be limited
with respect to metric group names.

Response body contents

On successful completion, the response body contains a JSON object with the following fields:

Field name Type Description

metrics-context-uri String/URI Canonical URI path of the metrics context object created by this operation
This includes the metrics-context-id. E.g. “/api/services/metrics/context/1”,
where “1” is the metrics-context-id.
metric-group-infos Array of Array of metric-group-info objects (described in the next table) that describe
objects the data format for each metric group that may be returned by future GETs
associated with this metric context.

Each nested metric-group-info object contains the following fields:

94 HMC Web Services API

 Level 04a

Field name Type Description

group-name String The name of the metric group for which we are providing descriptive
information.
metric-infos Array Array of metric-info objects (described in the next table). These describe each
metric for the group in the order that they will appear in future GETs
associated with this context.

Each nested metric-info object contains the following fields:

Field name Type Description

metric-name String The name of the metric.
metric-type String One of the following, describing the type of the metric:
Enum
"boolean-metric", "byte-metric", "double-metric", "long-metric",
"integer-metric", "short-metric", "string-metric"

See the Get Metrics “Response body contents” on page 98 for further
information on these metric types.

Description
This operation establishes a context for future Get Metrics operations that is valid for the current API
session. Because of the high frequency of invocation and large volume of data expected, the metrics
service interface has been structured to optimize the transmission of data on each Get Metrics request.
Thus, rather than use a self-describing representation for the results returned by each Get Metrics, the
metrics service instead provides the descriptive metadata as results from this Create Metrics Context
operation. It then returns the metric data in a compact format each time Get Metrics is invoked.

At a high level, the Create Metrics Context response communicates two primary pieces of information
back to the client. One is the metrics-context-uri, which includes the ID of the metrics context that must
be referenced on future GETs to associate them with this context. The other is the metric-groups
description data. That data provides the metric type and metric name information for each metric group
whose metrics may be returned by this context. This may be useful to the client for determining how to
parse future Get Metrics responses for this context, although the full documentation on metric group
formats is found in Chapter 9, “Metric groups,” on page 103.

The anticipated-frequency-seconds specification which is required on the request body tells the metrics
service how frequently the client anticipates issuing Get Metrics requests against this context. The metrics
service may take no action based on this frequency, but reserves the right to invalidate and delete the
metrics context if 4 times the specified frequency passes without receipt of an associated Get Metrics
operation.

Optional result filtering is provided by field metric-groups on the request body. If a non-empty
metric-groups arrays is specified, then future Get Metrics operations associated with this context will
return only groups with names listed there.

Additionally, if a metric-groups array of group names is specified on the Create Metrics Context request,
then the response JSON document will include only matching metric-group-info fields. If one or more
names in the metric-groups array does not represent a metric group registered on the HMC, then HTTP
error status code 400 (Bad Request) will be returned and the context will not be established.

Although the POST response fully describes and guarantees the ordering of metric-infos within a metric
group for that context, as a matter of policy the HMC will further guarantee that, for a given metric
group, any additions of new metrics to the group will be to the end of the list for the group.

Chapter 8. Inventory and metrics services 95

 Level 04a

Authorization requirements
There are no authorization restrictions on creating a metrics context. However any future metric results
returned by Get Metrics queries against that context will be restricted to managed objects accessible
according to the permissions associated with the API session under which the metrics context was
established.

Note that there is no indication via an HTTP status or reason code that future results may be restricted
due to authorization restrictions. Rather, success is indicated and future Get Metrics responses behave
just as if any restricted objects did not exist.

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and the response body is provided as described
in “Response body contents” on page 94. The URI for the newly created context is also provided in the
Location header of the response.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

Note: These are example rather than actual metrics group names.

POST /api/services/metrics/context HTTP/1.1

x-api-session: 6a9oz3ymut6rvjijrft0loqhfzgpp0rnu4mjishwh6d39jh31q
content-type: application/json
content-length: 96
{
"anticipated-frequency-seconds": 45,
"metric-groups": [
"virtualization-host-cpu-memory-usage"
]
}

Figure 17. Create Metrics Context: Request

96 HMC Web Services API

 Level 04a

201 Created
transfer-encoding: chunked
server: zSeries management console API web server / 1.0
location: /api/services/metrics/context/1
cache-control: no-cache
date: Wed, 07 Dec 2011 04:01:59 GMT
content-type: application/json;charset=UTF-8
{
"metric-group-infos": [
{
"group-name": "virtualization-host-cpu-memory-usage",
"metric-infos": [
{
"metric-name": "processor-usage",
"metric-type": "integer-metric"
},
{
"metric-name": "memory-usage",
"metric-type": "integer-metric"
},
{
"metric-name": "network-usage",
"metric-type": "integer-metric"
},
{
"metric-name": "storage-rate",
"metric-type": "integer-metric"
},
{
"metric-name": "physical-cpu-time",
"metric-type": "long-metric"
},
{
"metric-name": "memory-used",
"metric-type": "integer-metric"
},
{
"metric-name": "virt-host-management-cpu-time-used",
"metric-type": "long-metric"
},
{
"metric-name": "virt-host-page-ins",
"metric-type": "long-metric"
},
{
"metric-name": "virt-host-page-outs",
"metric-type": "long-metric"
}
]
}
],
"metrics-context-uri": "/api/services/metrics/context/1"
}

Figure 18. Create Metrics Context: Response

Get Metrics
The Get Metrics operation retrieves the current set of metrics associated with an established metrics
context.

Chapter 8. Inventory and metrics services 97

 Level 04a

HTTP method and URI

GET /api/services/metrics/context/{metrics-context-id}

In this request, the URI variable {metrics-context-id} is the identifier of the metrics context object for which
metrics are to be obtained.

Response body contents

On successful completion, the response body contains the set of metrics associated with the metrics
context. The response is sent using HTTP chunked transfer encoding and UTF-8 character encoding. A
MIME media type of application/vnd.ibm-z-zmanager-metrics is used and is specified in the
Content-Type header on the response.

Because performance and scalability are a major concern for the metrics service, the response body is in a
terse custom format, rather than being presented as a JSON object. The data type, name, and order
information required to parse and interpret the response is provided in a previous Create Metrics
Context response.

Data in this format will be delimited by newlines and commas.

Using a partial Extended Backus-Naur Form, where a comma (,) indicates concatenation and curly braces
({}) indicate 0 or more repetitions, we can express the format this way:

MetricsResponse = {MetricsGroup},NL

MetricsGroup = MetricsGroupName,NL,{ObjectValues},NL
MetricsGroupName = StringValue

NL = “\n”

ObjectValues = ObjectURI,NL,Timestamp,NL,ValueRows,NL

Timestamp = LongValue

ObjectURI = StringValue

ValueRows = ValueRow,{ValueRow}
ValueRow = Value,{“,”,Value},NL

Value = BooleanValue | ByteValue | DoubleValue | LongValue | IntegerValue | ShortValue | StringValue

The MetricsGroupName is the name of the metrics group, as a StringValue as defined below.

The Timestamp is the time when the associated values were buffered (i.e. “cached”) on the HMC. It is
expressed as an “epoch” timestamp: a LongValue giving the milliseconds since January 1, 1970, 00:00:00
GMT (just as is expected, for example, by the constructor of a java.util.Date object).

The ObjectURI is the canonical URI of the object, as a StringValue as defined below.

NL is a single newline character (Unicode U+000A).

All the varieties of Value will be represented as strings according to the following rules and limits:
v BooleanValue
– Either the string true or the string false.
v ByteValue
– A string representation of a signed decimal integer in the range -128 to 127 (i.e. the range of a
signed 8 bit integer).
v DoubleValue

98 HMC Web Services API

 Level 04a

– A string representation of a 64 bit IEEE 754 floating point number in the range +/-4.9E-324 to
+/-3.4028235E+38. Note that, although IEEE 754 provides for representations of positive or negative
Infinity and NaN, such values are not allowed in the metric data feed and thus will not appear in a
metrics service result. For results with a magnitude greater than or equal to 10^-3 and less than
10^7, the string representation will be a dotted decimal (e.g. 1.7, -32.467). For results with
magnitudes outside that range, the string representation will be computerized scientific notation
(e.g. -4.23E127).
v LongValue
– A string representation of a signed decimal integer in the range -9223372036854775808 to
9223372036854775807 (i.e. the range of a signed 64 bit integer).
v IntegerValue
– A string representation of a signed decimal integer in the range -2147483648 to 2147483647 (i.e. the
range of a signed 32 bit integer).
v ShortValue
– A string representation of a signed decimal integer in the range -32768 to 32767 (i.e. the range of a
signed 16 bit integer).
v StringValue
– A string starting with a double-quote, ending with a double-quote, and with any embedded
double-quotes or backslashes escaped with a preceding backslash (i.e. escaped as \" and \\).

Description
On successful execution status code 200 (OK) is returned, with a response body as described above.

The URI path on the request must designate an existing metrics context for the current API session. If the
URI designates an unrecognized context for the API session, then status code 404 (Not Found) is
returned.

Note that under some circumstances the metrics service may delete a metrics context, requiring the client
to establish a new context in order to resume metric retrievals. For example, the metrics service may
choose to delete a given context if the time since the last associated Get Metrics request has exceeded 4
times the anticipated frequency specified when the context was created. In addition, the client may
explicitly delete a metrics context with the Delete Metrics Context operation. If the URI designates a
context that was once valid for the current API session, but no longer is, then status code 409 (Conflict) is
returned.

Authorization requirements
Only metrics referencing managed objects accessible according to the permissions associated with the API
session under which the Get Metrics is being issued will be returned. Note that there is no indication via
an HTTP status or reason code that results may have been restricted due to authorization restrictions.
Rather, success is indicated and the responses are just as if any restricted objects did not exist.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 98.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.

Chapter 8. Inventory and metrics services 99

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The metrics context ID in the URI ({metrics-context-id}) does not designate a
metrics context for the associated API session.
409 (Conflict) 1 The metrics context ID in the URI ({metrics-context-id}) designates a metrics
context for the associated API session that is no longer valid.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Usage notes
v Repeated metrics retrievals, even consecutive retrievals against a common metrics context, will not
necessarily yield metrics for the exact same set of objects. Objects can come and go from the system's
inventory due to various circumstances unrelated to the metrics data. The metrics feed for a particular
metric group may stop for some reason, and the metrics data may therefore expire from the HMC's
buffer (i.e. the metrics cache). The access permissions of a user associated with a metrics context may
change, giving the user access to a smaller or larger set of objects (and therefore, perhaps, a smaller or
larger set of metrics data).
v It is possible that there may be no metrics to return for one or more metric groups associated with the
specified metrics context. For example, data for a metric group may not be buffered on the HMC at the
time of the Get Metrics invocation, or authorization restrictions related to objects in a requested metric
group may prevent any metrics for that group from being returned. If there is no metric data to be
returned for a metric group name, then that group name does not appear in the response body.
Furthermore, if there is no metric data to return for any metric group name associated with a context,
the response body format above specifies that the body will consist only of a single newline character.
This is nonetheless considered a successful response. In other words, an HTTP status code 200 (OK)
will still be returned with such a response.

Example HTTP interaction

GET /api/services/metrics/context/1 HTTP/1.1

x-api-session: 4g33uc2vith3v42vmce8wjr5q7x58x5ybh6hwd4vjpwr7jl4sz

Figure 19. Get Metrics: Request

100 HMC Web Services API

 Level 04a

200 OK
transfer-encoding: chunked
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 04:38:20 GMT
content-type: application/vnd.ibm-z-zmanager-metrics;charset=UTF-8
"virtualization-host-cpu-memory-usage"
"/api/virtualization-hosts/2f7bf364-03f8-11e1-8eda-001f163805d8"
1323232689283
0,14,0,3,2942386000,4608,2942386000,0,0

"/api/virtualization-hosts/c14cde64-03e6-11e1-baf3-001f163805d8"
1323232689283
0,64,-1,-1,76028000,1311,-1,-1,-1

"/api/virtualization-hosts/5f805d28-03e6-11e1-baf3-001f163805d8"
1323232689283
3,72,-1,-1,1731046000,1485,-1,-1,-1

"/api/virtualization-hosts/634fa694-03f4-11e1-881f-001f163805d8"
1323232689283
4,36,-1,-1,55878116000,17920,-1,-1,-1
<3 blank lines here (consecutive new lines)>

Figure 20. Get Metrics: Response

Delete Metrics Context

The Delete Metrics Context operation deletes a metrics context.

HTTP method and URI

DELETE /api/services/metrics/context/{metrics-context-id}

In this request, the URI variable {metrics-context-id} is the identifier of the metrics context object for which
metrics are to be obtained.

Description
This operation deletes the metrics context ID. That is, it disassociates it from the API session and cleans
up any data associated with it. Further Get Metrics requests against this context will result in status code
409 (Conflict).

The URI path must designate an existing valid metrics context for the current API session. If the URI
path represents an already invalidated metrics context for the current API session, status code 409
(Conflict) is returned. If the URI path does not represent a recognized metrics context for the current API
session, status code 404 (Not Found) is returned.

Authorization requirements
There are no authorization requirements for deleting a metrics context. The association with the API
session is implicit, so there is no possibility of deleting a context that was created by a different API
session. In other words, only the session which created a metrics context can delete it.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

Chapter 8. Inventory and metrics services 101

 Level 04a

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The metrics context ID in the URI ({metrics-context-id}) does not designate a
metrics context for the associated API session.
409 (Conflict) 1 The metrics context ID in the URI ({metrics-context-id}) designates a metrics
context for the associated API session that is no longer valid.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

DELETE /api/services/metrics/context/1 HTTP/1.1

x-api-session: 6a9oz3ymut6rvjijrft0loqhfzgpp0rnu4mjishwh6d39jh31q

Figure 21. Delete Metrics Context: Request

204 No Content
date: Wed, 07 Dec 2011 04:01:59 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 22. Delete Metrics Context: Response

102 HMC Web Services API

 Level 04a

Chapter 9. Metric groups

This chapter provides a description of the metric groups that can be retrieved using the Metrics Service.
For each metric group provided by the HMC, the material in this chapter describes the purpose and
general characteristics of the metric group, and then defines the content of the metric group via a table
that specifies the metric fields provided by the group. The order in which metric fields appear within
these tables corresponds to the order in which the data items appear in a value row returned by the Get
Metrics operation. For example, the metric field appearing in the first row of a metric group table (and
identified in a table below as being in position 1) will be the first data item provided in a value row for
that metric group; the metric field appearing in the second row (position 2) will be the next data item in
a value row, and so on. Thus, the order in which metric fields are documented here is considered
semantically significant and can be relied upon by client applications in order to simplify parsing of the
data retrieved using the Get Metrics operation.

The contents of metric groups may be extended in future versions of this API. If a metric group is
extended, new metric fields will be added to the end so as to not alter the relative positions of any of the
existing fields. Such new fields would not be understood by a client application designed for an earlier
version of the API. Therefore, applications must be developed using the philosophy of "ignore what you
don't understand/expect" when processing metric group data in order to tolerate such possible future
extensions. See “Compatibility” on page 6 for more discussion on API compatibility principles.

Monitors dashboard metric groups

The Monitors Dashboard task is the current system monitoring interface on the HMC. It gives a
dashboard display to monitor system resources, such as power consumption, environmental data,
processor usage, etc.

In order to provide programmatic access to this same data, the utilization and environment data that is
displayed on the user interface is also provided via the Metrics Service in the following metric groups.

BladeCenter temperature and power metric group

This metric group reports the ambient temperature and power consumption for each BladeCenter on the
system.
Metric Group Name
"bladecenter-temperature-and-power"
Collection Interval
15 seconds
Applicable Managed Object Class
"bladecenter"

The following metrics are provided in each entry of this metric group:
Table 26. BladeCenter temperature and power metric group
Pos Metric field name Type Units Description
1 temperature-celsius Double Degrees The ambient temperature
Celsius
2 power-consumption-watts Integer Watts The power consumption

© Copyright IBM Corp. 2017, 2018 103

 Level 04a

Blade power
This metric group reports power consumption for each blade on the system.
Metric Group Name
"blade-power-consumption"
Collection Interval
15 seconds
Applicable Managed Object Class
"blade"

The following metrics are provided in each entry of this metric group:
Table 27. Blade power metric group
Pos Metric field name Type Units Description
1 power-consumption-watts Integer Watts The power consumption

Channels
This metric group reports the channel usage for each channel on the system. An instance of this metric
group is created for each channel of a CPC.
Metric Group Name
"channel-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 28. Channels metric group
Pos Metric field name Type Units Description
1 channel-name String — The name of the channel in the form CSS.Chpid
2 shared-channel Boolean — True if the channel is shared among logical partitions, and
false if it is not
3 logical-partition-name String — For channel types for which logical partition names are
available, the name of the owning logical partition or the
value "shared" if the channel is shared. For other channel
types for which the name is not available (for example,
coupling channels), the value is always an empty string.
4 channel-usage Integer % The channel percent usage (0 – 100%)

CPC overview
This metric group reports the aggregated processor usage and channel usage, the ambient temperature,
and total system power consumption for each system. The cpc-processor-usage is the average of the
percentages of processing capacity for all the physical processors in the CPC. The channel-usage is the
average of the percentages of I/O capacity for all the channels and adapters in the CPC.
Metric Group Name
"cpc-usage-overview"
Collection Interval
15 seconds

104 HMC Web Services API

 Level 04a

Applicable Managed Object Class

"cpc"

The following metrics are provided in each entry of this metric group:
Table 29. CPC overview metric group
Pos Metric field name Type Units Description
1 cpc-processor-usage Integer % The processor percent usage.
2 channel-usage Integer % The channel percent usage.
3 power-consumption-watts Integer Watts The total system power consumption.
4 temperature-celsius Double Degrees The ambient temperature.
Celsius
5 cp-shared-processor-usage Integer % The processor percent usage for all CP shared processors.
Set to -1 if there are no processors of this type.
6 cp-dedicated-processor-usage Integer % The processor percent usage for all CP dedicated
processors. Set to -1 if there are no processors of this type.
7 ifl-shared-processor-usage Integer % The processor percent usage for all IFL shared processors.
Set to -1 if there are no processors of this type.
8 ifl-dedicated-processor-usage Integer % The processor percent usage for all IFL dedicated
processors. Set to -1 if there are no processors of this type.
9 icf-shared-processor-usage Integer % The processor percent usage for all ICF shared processors.
Set to -1 if there are no processors of this type.
10 icf-dedicated-processor-usage Integer % The processor percent usage for all ICF dedicated
processors. Set to -1 if there are no processors of this type.
11 iip-shared-processor-usage Integer % The processor percent usage for all zIIP shared processors.
Set to -1 if there are no processors of this type.
12 iip-dedicated-processor-usage Integer % The processor percent usage for all zIIP dedicated
processors. Set to -1 if there are no processors of this type.
13 aap-shared-processor-usage Integer % The processor percent usage for all zAAP shared
processors. Set to -1 if there are no processors of this type.
14 aap-dedicated-processor- Integer % The processor percent usage for all zAAP dedicated
usage processors. Set to -1 if there are no processors of this type.
15 all-shared-processor-usage Integer % The processor percent usage for all shared processors. Set
to -1 if there are no processors of this type.
16 all-dedicated-processor-usage Integer % The processor percent usage for all dedicated processors.
Set to -1 if there are no processors of this type.
17 cp-all-processor-usage Integer % The processor percent usage for all CP processors. Set to -1
if there are no processors of this type.
18 ifl-all-processor-usage Integer % The processor percent usage for all IFL processors. Set to -1
if there are no processors of this type.
19 icf-all-processor-usage Integer % The processor percent usage for all ICF processors. Set to -1
if there are no processors of this type.
20 iip-all-processor-usage Integer % The processor percent usage for all zIIP processors. Set to
-1 if there are no processors of this type.
| 21 cbp-shared-processor-usage Integer % The processor percent usage for all CBP shared processors.
| Set to -1 if there are no processors of this type.
| 22 cbp-dedicated-processor- Integer % The processor percent usage for all CBP dedicated
| usage processors. Set to -1 if there are no processors of this type
| 23 cbp-all-processor-usage Integer % The processor percent usage for all CBP processors. Set to
| -1 if there are no processors of this type.

Chapter 9. Metric groups 105

 Level 04a

zBX (Node) overview

This metric group reports the average processor usage and network I/O usage, ambient temperature, and
total system power for each zBX node. The processor usage is the average percent usage of all processors.
The network I/O usage is the average percent usage of all the blades that support network I/O. The
ambient temperature value is the average of the ambient temperature values for all BladeCenter chassis.
An instance of this metric group is created for each zBX node.
Metric Group Name
"zbx-node-usage-overview"
Collection Interval
15 seconds
Applicable Managed Object Class
"zbx" (when type is "node")

The following metrics are provided in each entry of this metric group:
Table 30. zBX node overview metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % The average percent usage of all processors.
2 io-usage Integer % The average I/O percent usage for all blades that support
network I/O.
3 power-consumption-watts Integer Watts The total system power consumption. This includes the
zBX node and all its blades and BladeCenter chassis.
4 temperature-celsius Double Degrees The average ambient temperature of all BladeCenter
Celsius chassis.

DPM system overview

This metric group reports the aggregated processor usage, network usage, storage usage, accelerator
usage, crypto usage, power consumption and temperature for each DPM enabled system.
Metric Group Name
"dpm-system-usage-overview"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 31. DPM system overview metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % The processor percent usage.
2 network-usage Integer % The network percent usage. Set to -1 if there are no
adapters of this type.
3 storage-usage Integer % The storage percent usage. Set to -1 if there are no adapters
of this type.
4 accelerator-usage Integer % The accelerator percent usage. Set to -1 if there are no
adapters of this type.

106 HMC Web Services API

 Level 04a

Table 31. DPM system overview metric group (continued)

Pos Metric field name Type Units Description
5 crypto-usage Integer % The crypto percent usage. Set to -1 if there are no adapters
of this type.
6 power-consumption-watts Integer Watts The power consumption in watts.
7 temperature-celsius Double Degrees The ambient temperature.
Celsius
8 cp-shared-processor-usage Integer % The processor percent usage for all CP shared processors.
Set to -1 if there are no processors of this type.
9 cp-all-processor-usage Integer % The processor percent usage for all CP processors. Set to -1
if there are no processors of this type.
10 ifl-shared-processor-usage Integer % The processor percent usage for all IFL shared processors.
Set to -1 if there are no processors of this type.
11 ifl-all-processor-usage Integer % The processor percent usage for all IFL processors. Set to -1
if there are no processors of this type.
12 all-shared-processor-usage Integer % The processor percent usage for all shared processors. Set
to -1 if there are no processors of this type.

Logical partitions
This metric group reports the processor usage and z/VM paging rate for each active logical partition (aka
Image, LPAR Image, Zone, PR/SM™ virtual server) on the system.
Metric Group Name
"logical-partition-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"logical-partition"

The following metrics are provided in each entry of this metric group:
Table 32. Logical partitions metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % The processor percent usage.
2 zvm-paging-rate Integer Pages The z/VM paging rate. Only returned for logical partitions
Per running z/VM level 6.1 or higher that have the appropriate
Second agent running in them.
3 cp-processor-usage Integer % The processor percent usage for all CP processors. Set to -1
if there are no processors of this type.
4 ifl-processor-usage Integer % The processor percent usage for all IFL processors. Set to -1
if there are no processors of this type.
5 icf-processor-usage Integer % The processor percent usage for all ICF processors. Set to -1
if there are no processors of this type.
6 iip-processor-usage Integer % The processor percent usage for all IIP processors. Set to -1
if there are no processors of this type.
| 7 cbp-processor-usage Integer % The processor percent usage for all CBP processors. Set to -1
| if there are no processors of this type.

Chapter 9. Metric groups 107

 Level 04a

Partitions
This metric group reports the processor usage, network usage, storage usage, accelerator usage, and
crypto usage for each active partition on a DPM enabled system.
Metric Group Name
"partition-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"partition"

The following metrics are provided in each entry of this metric group:
Table 33. Partitions metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % The processor percent usage.
2 network-usage Integer % The network percent usage. Set to -1 if there are no
adapters of this type.
3 storage-usage Integer % The storage percent usage. Set to -1 if there are no
adapters of this type.
4 accelerator-usage Integer % The accelerator percent usage. Set to -1 if there are no
adapters of this type.
5 crypto-usage Integer % The crypto percent usage. Set to -1 if there are no
adapters of this type.

zCPC environmentals and power

This metric group reports environmental data and power consumption for the zCPC, which is the legacy
part of the system; i.e. without blades.
Metric Group Name
"zcpc-environmentals-and-power"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 34. zCPC environmentals and power metric group
Pos Metric field name Type Units Description
1 temperature-celsius Double Degrees The ambient temperature
Celsius
2 humidity Integer % The relative humidity
3 dew-point-celsius Double Degrees The dew point
Celsius
4 power-consumption-watts Integer Watts The power consumption in watts
5 heat-load Integer Btu/ The total heat load of the system (heat load forced-air +
hour heat load water)
6 heat-load-forced-air Integer Btu/ The heat load covered by forced-air
hour

108 HMC Web Services API

 Level 04a

Table 34. zCPC environmentals and power metric group (continued)

Pos Metric field name Type Units Description
7 heat-load-water Integer Btu/ The heat load covered by water
hour
8 exhaust-temperature-celsius Double Degrees The exhaust temperature
Celsius

zCPC processors
This metric group reports the processor usage for each physical zCPC processor on the system. This
includes the System Assist Processors (SAPs) and does not include blades. An instance of this metric
group is created for each processor of a CPC.
Metric Group Name
"zcpc-processor-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 35. zCPC processors metric group
Pos Metric field name Type Units Description
1 processor-name String The name of the zCPC processor in the form
processor-type + processor ID. For example, IFL01.
2 processor-type String The type of zCPC processor. The valid types are:
| "cp", "ifl", "icf", "iip", "aap", "sap" and "cbp". The
valid types for DPM enabled systems are: "cp",
"ifl", and "sap".
3 processor-usage Integer % The processor percent usage.
4 smt-usage Integer % The percentage of time the processor is running in
simultaneous multithreading (SMT) mode. Set to -1
when SMT mode is not supported by the CPC.
5 thread-0-usage Integer % The percent usage of thread 0 when the processor
is running in simultaneous multithreading (SMT)
mode. Set to -1 when SMT mode is not supported
by the CPC.
6 thread-1-usage Integer % The percent usage of thread 1 when the processor
is running in simultaneous multithreading (SMT)
mode. Set to -1 when SMT mode is not supported
by the CPC.

Blade CPU and memory metric group

This metric group reports CPU and memory utilization for each of the blades in the ensemble. This group
provides data for all types of blades.
Metric Group Name
"blade-cpu-memory-usage"
Collection Interval
15 seconds

Chapter 9. Metric groups 109

 Level 04a

Applicable Managed Object Class

"blade"

The following metrics are provided in each entry of this metric group:
Table 36. Blade CPU and memory metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % Processor utilization percentage (0-100%). Value for
current interval. If the value is not currently available,
for example if the blade is powered off, -1 is provided.
2 memory-usage Integer % Memory utilization percentage (0-100%). Value for
current interval. If the value is not currently available,
for example if the blade is powered off, -1 is provided.

Cryptos
This metric group reports the adapter usage for each crypto on the system. An instance of this metric
group is created for each crypto adapter. This metric group is not used for a DPM system. For DPM,
crypto adapters are reported in the Adapters metric group. See “Adapters.”
Metric Group Name
"crypto-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 37. Crypto metric group
Pos Metric field name Type Units Description
1 channel-id String The physical channel identifier of the crypto
2 crypto-id String The crypto identifier of the crypto, decimal 0-15
3 adapter-usage Integer % The adapter percent usage (0-100%)

Adapters
This metric group reports the adapter usage for each adapter on the DPM enabled system. An instance of
this metric group is created for each adapter.
Metric Group Name
"adapter-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"adapter"

The following metrics are provided in each entry of this metric group:
Table 38. Adapters metric group
Pos Metric field name Type Units Description
1 adapter-usage Integer % The adapter percent usage

110 HMC Web Services API

 Level 04a

Flash memory adapters

This metric group reports the adapter usage for each Flash memory (Flash Express) adapter on the
system. An instance of this metric group is created for each Flash memory adapter of the CPC. If a CPC
has no flash memory adapters, then no data will appear in this metric group for that CPC.

Note: Flash Express has a planned exploitation of December 2012.

Metric Group Name
"flash-memory-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 39. Flash memory adapters metric group
Pos Metric field name Type Units Description
1 channel-id String The physical channel identifier of the Flash memory
adapter
2 adapter-usage Integer % The adapter percent usage (0-100%)

RoCE adapters
This metric group reports the adapter usage for each RoCE (10GbE RoCE) adapter on the system. An
instance of this metric group is created for each RoCE adapter of the CPC.
Metric Group Name
"roce-usage"
Collection Interval
15 seconds
Applicable Managed Object Class
"cpc"

The following metrics are provided in each entry of this metric group:
Table 40. RoCE adapters metric group
Pos Metric field name Type Units Description
1 channel-id String The physical channel identifier of the RoCE adapter
2 adapter-usage Integer % The adapter percent usage (0-100%)

Ensemble power
This metric group reports the consumption for the Ensemble. An instance of this metric group is created
for the Ensemble, if one exists on the HMC.
Metric Group Name
"ensemble-power"
Collection Interval
15 seconds
Applicable Managed Object Class
"ensemble"

Chapter 9. Metric groups 111

 Level 04a

The following metrics are provided in each entry of this metric group:
Table 41. Ensemble power metric group
Pos Metric field name Type Units Description
1 power-consumption-watts Integer Watts The total power consumption of all members of the
Ensemble.

Performance management metrics groups

Following are the performance management metrics groups.

Virtual server CPU and memory metrics group

This metric group is collected for all types of virtual servers: PowerVM, PR/SM, x Hyp, and z/VM.
Metric Group Name
"virtual-server-cpu-memory-usage"
Collection Interval
15 seconds for PR/SM, x Hyp and z/VM virtual servers
30 seconds for PowerVM virtual servers
Applicable Managed Object Class
"virtual-server"

The following metrics are provided in each entry of this metric group:
Table 42. Virtual server CPU and memory metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % Physical utilization percentage (0-100%). Values
for current interval.
2 memory-usage Integer % Memory usage percentage (0-100%). Value for
current interval.
3 up-time Long Microseconds Time since the virtual server was started. Not
supported for PR/SM, will be reported as -1.
4 physical-cpu-time Long Microseconds Physical CPU time used by virtual server. This
time accumulates until the virtualization host or
the support element is restarted.
5 virt-host-cpu-delay-time Long Microseconds The virtual processors were ready to run but not
dispatched on physical processors due to
competition with other virtual servers. This time
accumulates until the virtualization host or the
support element is restarted.Not supported for
PR/SM, will be reported as -1.
6 elapsed-time Long Microseconds Elapsed time over which physical-cpu-time and
virt-host-cpu-delay-time have accumulated.
7 cpu-allocation Integer Share for z/VM Amount of CPU resource allocated to virtual
and x Hyp, server. zManager adjusts this value when virtual
physical CPU server management is enabled. For PowerVM,
equivalent for this is the processing units setting. For z/VM
PowerVM, and and x Hyp, this is the CPU share value. For
processing PS/SM this is the general purpose processing
weight for weight setting. Not supported for virtual servers
PR/SM with dedicated virtual processors, will be
reported as -1.

112 HMC Web Services API

 Level 04a

Table 42. Virtual server CPU and memory metric group (continued)
Pos Metric field name Type Units Description
8 current-physical-memory- Integer Megabytes Amount of physical memory currently used by
used virtual server.
9 os-total-cpu-using-samples1 Long Count Count of samples where virtual CPUs were seen
in use. Will be 0 if GPMP not running on virtual
server.
10 os-total-cpu-delay-samples1 Long Count Count of samples where threads were delayed
waiting for virtual CPUs. Will be 0 if GPMP not
running on virtual server.
11 os-total-paging-delay- Long Count Count of samples where threads were delayed
samples1 waiting for page faults to be resolved. Will be 0
if GPMP not running on virtual server.
12 os-total-io-delay-sample1 Long Count Count of samples where threads were delayed
waiting for I/O to complete. Will be 0 if GPMP
not running on virtual server.
13 os-sampling-rate Integer Samples per Number of times per second OS samples are
second collected. Will be 0 if GPMP not running on
virtual server.
14 os-total-other-samples1 Long Count Count of samples where processes where in a
state not included in the other sample counts.
15 gpmp-active Boolean True if the GPMP was active on the virtual
server at the end of the interval. False otherwise.
16 other-time Long Microseconds Sum of time any of the virtual processors of the
virtual server where in a state other than
dispatched on physical processors, delayed, or
idle.
17 idle-time Long Microseconds Sum of the time any of the virtual processors of
the virtual server were idle.
18 virtual-cpu-count Integer Count Number of virtual processors defined for the
virtual server, totaled across all types
(dedicated/shared, CP/IFL/zIIP/zAAP)
Note:
1. On an interval basis the GPMP samples the state of OS threads. Each sampling interval the GPMP counts
the number of threads in various states. Each of these states represents a sample type. The sample types
are:
v CPU Using: Each sample represents a thread found actively running on a virtual processor
v CPU delay: Each sample represents a thread waiting to be dispatched on a virtual processor
v Page Delay: Each sample represents a thread waiting for a page fault to be resolved
v I/O Delay: Each sample represents a threads waiting for I/O to complete
v Other: Each sample represents processes that had no threads in one of the above states.
The GPMP keeps a running total for each sample type. These running totals are returned in the sample
metrics that are part of the virtual-server-cpu-memory-usage metrics group. The sampling interval is
returned in the os-sampling-rate metric.

Virtualization host CPU and memory metrics group

Metric Group Name
"virtualization-host-cpu-memory-usage"
Collection Interval
15 seconds for PR/SM, x Hyp and z/VM virtualization hosts

Chapter 9. Metric groups 113

 Level 04a

30 seconds for PowerVM virtualization hosts

Applicable Managed Object Class
"virtualization-host"

The following metrics are provided in each entry of this metric group:
Table 43. Virtualization host CPU and memory metric group
Pos Metric field name Type Units Description
1 processor-usage Integer % Overall CPU utilization percentage for the
virtualization host (0-100%). Value for current
interval. For PR/SM only includes general
purpose processors.
2 memory-usage Integer % Memory usage percentage for the virtualization
host (0-100%). Value for current interval.
3 network-usage Integer % Network utilization percentage for the
virtualization host (0-100%). Value for current
interval. Not available for z/VM or PR/SM, will
be reported as -1.
4 storage-rate Integer Kbytes per sec Average Kbytes transferred to disk over interval.
Value for current interval. Not available for
z/VM or PR/SM, will be reported as -1.
5 physical-cpu-time Long Microseconds Physical CPU time used. Cumulative value.For
PR/SM only includes general purpose
processors.
6 memory-used Integer Mbytes Current memory in use by the virtualization
host.
7 virt-host-management-cpu-time- Long Microseconds CPU time used for virtualization host
used management. Cumulative value. Note for
PowerVM this is the CPU used by the VIOS
partition. For x Hyp this is the Linux system
mode CPU time. Currently not supported for
z/VM or PR/SM, will be reported as -1.
8 virt-host-page-ins Long Count Paging activity by the virtualization host to
support hypervisor management. Page reads
from paging space. Cumulative value. For
PowerVM this represents VIOS paging. For x
Hyp it is the base Linux paging. Currently not
supported for z/VM or PR/SM, will be reported
as -1.
9 virt-host-page-outs Long Count Paging activity by the virtualization host to
support hypervisor management. Page written to
paging space. Cumulative value. For PowerVM
this represents VIOS paging. For x Hyp it is the
base Linux paging. Currently not supported for
z/VM or PR/SM, will be reported as -1.
10 cp-cpu-time1 Long Microsecond CPU time accumulated by the general purpose
processors owned by the virtualization host.
Only supported for z/VM, will be reported as -1
for other hypervisor types.
11 ifl-cpu-time1 Long Microsecond CPU time accumulated by the IFL processors
owned by the virtualization host. Only
supported for z/VM, will be reported as -1 for
other virtualization host types.

114 HMC Web Services API

 Level 04a

Table 43. Virtualization host CPU and memory metric group (continued)
Pos Metric field name Type Units Description
1
12 zaap-cpu-time Long Microsecond CPU time accumulated by the zAAP processors
owned by the virtualization host. Only
supported for z/VM, will be reported as -1 for
other virtualization host types.
13 ziip-cpu-time1 Long Microsecond CPU time accumulated by the zIIP processors
owned by the virtualization host. Only
supported for z/VM, will be reported as -1 for
other virtualization host types.
14 icf-cpu-time1 Long Microsecond CPU time accumulated by the ICF processors
owned by the virtualization host. Only
supported for z/VM, will be reported as -1 for
other virtualization host types.
Table Notes:
1. Provided for virtualization hosts on CPCs with SE version 2.12.0 or later; metric not present for CPCs with
earlier SE versions.

Workload service class data metrics group

This metric group reports workload performance data on a per-service-class basis. At each collection
interval for a given workload, one instance of this metric group is added to the metric cache for each
service class of the active policy for that workload.
Metric Group Name
"workload-service-class"
Collection Interval
15 seconds
Applicable Managed Object Class
"workload"

The following metrics are provided in each entry of this metric group:
Table 44. Workload metrics group - service class data metric group
Pos Metric field name Type Units Description
1 policy-activation-time Long Timestamp Time of the last policy activation for this workload.
This is the last-activation-requested-date property
of the currently active policy.
2 service-class-name String — Name of service class
(1-64)
3 velocity-numerator Long Microseconds Time value used for numerator of velocity
calculation. Cumulative value since last policy
activation.
4 velocity-denominator Long Microseconds Time value used for denominator of velocity
calculation. Cumulative value since last policy
activation.

Network management metrics

Following are the network management metric groups.

Chapter 9. Metric groups 115

 Level 04a

Virtualization host and virtual server metrics

The zManager Metrics Service provides network metrics for Z network resources. These metrics are
collected at the virtualization host (hypervisor) network layer. The virtualization host provides a virtual
LAN for network communications between the virtual servers it is hosting, and transparently virtualizes
the attached physical network interfaces providing server access to the physical network. In many cases,
this network virtualization function within the virtualization host is commonly referred to as the “virtual
switch” or “vSwitch”. In zManager, although only certain zManager platforms allow for explicit external
exposure and management of the vSwitch, the network metrics collected at this layer will be exposed for
each platform. In some cases, such as "zvm" and "prsm", the virtualization host supports multiple
vSwitches, and the vSwitches are externally identified within zManager. For example, in zManager, OSX
and IQD-X chpids are referred to as vSwitches. The term “vSwitch” is also used to generically describe
the network functions of the virtualization host. For "x-hyp", "power-vm", and "prsm" virtualization host
types, a specific vSwitch resource is not explicitly externalized for management within zManager;
therefore, it is the virtualization host itself that is associated with the metrics, and, where the metric
group provides a vSwitch name, this value will be “N/A”. In these cases, the virtualization host
implicitly represents a single vSwitch.

The network metrics provided at the virtualization host are the following:
v Virtualization host uplink metrics: Virtual network (i.e. per VLAN ID) metrics are not provided for
uplinks. . Metrics collected are provided on an interval. These metrics can be collected from the
Virtualization Host (vSwitch) Uplink Metric Group. Metrics for two types of uplinks are provide:
– Real Uplinks: These are metrics which are captured between the virtualization host or virtualization
host's vSwitch and the attached physical network interfaces. These metrics can show the bandwidth
that the virtualization host is contributing to the IEDN.
– Virtual Uplinks: These metrics are captured by these vSwitch ports which are not directly attached
to a physical vSwitch that attaches to the IEDN. The following describe the supported virtual
uplinks:
- An IQD-X chpid that is attached to a z/VM LPAR's vSwitch bridge port. The z/VM vSwitch
bridge port provides the uplink from the IQD-X vSwitch.
- A z/VM vSwitch virtual uplink. A virtual uplink connects a vSwitch to a z/VM virtual server. In
this case, traffic is forwarded to this server, which may be useful for packet collection for
debugging or analysis.
v Virtualization host by vSwitch by virtual network metrics: These metrics are captured between the
virtualization host and its virtual servers. In cases, such as z/VM, where a virtualization host has
multiple vSwitches, the metrics are captured by virtualization host by vSwitch by virtual network.
These metrics can be collected from the Virtualization Host (vSwitch) by Virtual Network Metric
Group.
v Network metrics from virtualization host for each attached virtual server's virtual network adapter by
virtual network (VLAN ID): These metrics can be collected from the Attached Virtual Servers Network
Adapter Metric Group.

In general, for the Virtualization Host by Virtual Network Metrics Group and the Attached Virtual
Servers Network Adapter Metric Group, the metrics are collected at the virtualization host level for the
attached virtual server virtual network adapter by virtual network (VLAN ID). The network metrics
collected at this level provide a view of the performance between the virtual switch and the virtual
server, with metrics such as bytes sent and bytes received. Other metrics such as packets dropped or
discarded can help to determine if problems are occurring. Metrics are collected and provided on an
interval, and each metric provided is the total cumulative value, and not a delta.

Providing metrics at the virtualization host's virtual network adapters provides a level of granularity that
allows for the consumer to aggregate these metrics. Use of these metrics along with configuration data
provided through the zManager external API allow the client application to determine resource utilization
relationships.

116 HMC Web Services API

 Level 04a

Virtualization host (vSwitch) uplink metric group

This metric group provides virtualization host (hypervisor)-based network metrics for the uplink ports.
The metrics provided by this group represent the uplink metrics between the vSwitch and the physical
network interface. These metrics are from the perspective of the vSwitch sending to and receiving from
the physical network interfaces.

In the case of z/VM, there may be multiple uplink interfaces; therefore, multiple instances of this metric
group may be provided for a single z/VM virtualization host. This is also true for a PR/SM
virtualization host. For a PR/SM virtualization host, there may be multiple OSX's for which the uplink
information provides the metrics between the OSX and the physical network.

Metrics are collected and provided on an interval, and each metric provided is the total cumulative value,
and not a delta.
Metric Group Name
"network-virtualization-host-uplink"
Collection Interval
30 seconds
Applicable Managed Object Class
"virtualization-host"

The following metrics are provided in each entry of this metric group:
Table 45. Virtualization host (vSwitch) uplink metric group
Pos Metric field name Type Units Description
1 uplink-id String Name of the uplink interface.

The uplink names are described as follows and the

naming convention will be unique based upon the type
property of the virtualization-host object:
v "power-vm" - The names will be the platform-defined
names of the physical network interfaces, for example
“entx” or “enty”. Where x and y are numeric values.
v "x-hyp" - The names will be the platform-defined
names of the physical network interfaces, for example
“entx” or “enty”. Where x and y are numeric values.
v "prsm" - where the uplink is an OSX, the uplink is the
pchid. The name will be in the format of “OSX
pchid.port”
v "prsm" - where the uplink is an IQDX chpid that is
connected to a z/VM vSwitch bridge port. The name
will be in the form “IQDX css.chpid:zvm lpar
name.vswitch name.”
v "zvm" - If the uplink is OSX, then the uplink will
identify the OSA css and chpid, the z/VM LPAR name
and virtual device number of the OSX. The name will
be in the format of “OSX css.chpid:zvm lpar name.vdev
number”.
2 uplink-type String The uplink type is:
Enum v "real"
v "virtual"

Chapter 9. Metric groups 117

 Level 04a

Table 45. Virtualization host (vSwitch) uplink metric group (continued)

Pos Metric field name Type Units Description
3 vswitch-name String Name of the vSwitch. In the case where the vSwitch is
not uniquely identified for a virtual host then this will be
“N/A”.

“N/A” is returned for all virtualization-host objects

except where the type property of the virtualization-host
object is "zvm".
4 bytes-sent Long Count Number of bytes sent from the uplink interface to the
physical network.
5 bytes-received Long Count Number of bytes received by the uplink interface from
the physical network.
6 packets-sent Long Count Number of packets sent from the uplink interface to the
physical network.
7 packets-received Long Count Number of packets received by this uplink interface from
the physical network.
8 packets-sent-dropped Long Count Number of packets that were dropped when sending
from this uplink interface to the physical network.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
9 packets-received-dropped Long Count Number of packets received by this uplink interface from
the physical network that were dropped.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
10 packets-sent-discarded Long Count Number of packets that were discarded when sending
from the uplink interface to the physical network.

Packets may be discarded due to errors associated with

the packet, such as malformed packets.
11 packets-received-discarded Long Count Number of packets received by this uplink interface that
were discarded.

Packets may be discarded due to errors associated with

the packet, such as malformed packets.
12 multicast-packets-sent Long Count Number of multicast packets sent from the uplink
interface to the physical network.
13 multicast-packets-received Long Count Number of multicast packets received by the uplink
interface from the physical network.
14 broadcast-packets-sent Long Count Number of broadcast packets sent from the uplink
interface to the physical network.
15 broadcast-packets-received Long Count Number of broadcast packets received by this uplink
interface from the physical network.
16 interval-bytes-sent Long Bytes Number of bytes sent by this uplink interface to the
physical network over the collection interval.
17 interval-bytes-received Long Bytes Number of bytes received by this uplink interface from
the physical network over the collection interval.
18 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this uplink interface
Second to the physical network over the collection interval.

118 HMC Web Services API

 Level 04a

Table 45. Virtualization host (vSwitch) uplink metric group (continued)

Pos Metric field name Type Units Description
19 bytes-per-second-received Long Bytes per Number of bytes received per second by this uplink
Second interface from the physical network over the collection
interval.
20 mac-address String The MAC address of this uplink, if known. If it is not
known then “N/A”.
21 flags Long Flags indicating the types of metrics that are reported by
this uplink. The value of this field should be interpreted
as a bitmask. The meaning of each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are supported

Virtualization host (vSwitch) by virtual network metric group

The virtualization host (vSwitch) Virtual Network metric collection group provides virtual network
metrics by virtualization host by vSwitch by virtual network. These metrics are collected at the
virtualization host's vSwitch port level by virtual network and aggregated to provide metrics for each
vSwitch by virtual network. For each virtualization host there will be an instance of these metrics for
each vSwitch (in cases where multiple vSwitches are associated with the virtualization host) for each
virtual network (vlan-id); therefore, there may be multiple instances within the group. In cases where a
“vSwitch” is not externalized for the virtualization host, the name of the vSwitch is “N/A” and the
metrics are associated with the virtualization host. These metrics are essentially an aggregation of the
metrics from the “Attached virtual server network adapters metric group” on page 121.

Metrics are collected and provided on an interval, and each metric provided is the total cumulative value,
and not a delta.
Metric Group Name
"network-vswitch-by-virtual-network"
Collection Interval
30 seconds
Applicable Managed Object Class
"virtualization-host"

The following metrics are provided in each entry of this metric group:
Table 46. Virtualization host (vSwitch) by virtual network metric group
Pos Metric field name Type Units Description
1 vswitch-name String Name of the vSwitch. In the case where the vSwitch is
not uniquely identified for a virtual host then this will
be “N/A”.

“N/A” is returned for all virtualization-host objects

except where the type property of the virtualization-host
object is "zvm".

Chapter 9. Metric groups 119

 Level 04a

Table 46. Virtualization host (vSwitch) by virtual network metric group (continued)
Pos Metric field name Type Units Description
2 vlan-id Integer VLAN ID of the virtual network for which metrics are
being provided. This value corresponds to the vlan-id
property of the related Virtual Network object.

There may be cases where this field is 0 when metrics

are reported and the VLAN ID is unable to be
determined.
3 bytes-sent Long Count Number of bytes sent from this virtualization host or
virtualization host's vSwitch to the attached virtual
servers.
4 bytes-received Long Count Number of bytes received by this virtualization host or
virtualization host's vSwitch from the attached virtual
servers.
5 packets-sent Long Count Number of packets sent from this virtualization host or
virtualization host's vSwitch to the attached virtual
servers.
6 packets-received Long Count Number of packets received by this virtualization host or
virtualization host's vSwitch from the attached virtual
servers.
7 packets-sent-dropped Long Count Number of packets that were dropped when sending
from this virtualization host or virtualization host's
vSwitch to the attached virtual servers.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
8 packets-received-dropped Long Count Number of packets received by this virtualization host or
virtualization host's vSwitch from the attached virtual
servers that were dropped.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
9 packets-sent-discarded Long Count Number of packets that were discarded when sending
from this virtualization host or virtualization host's
vSwitch to the attached virtual servers.

Packets may be discarded due to errors associated with

the packet, such as malformed packets.
10 packets-received-discarded Long Count Number of packets received by this virtualization host or
virtualization host's vSwitch from the virtual servers that
were discarded.

Packets may be discarded due to errors associated with

the packet, such as malformed packets
11 multicast-packets-sent Long Count Number of multicast packets sent from this
virtualization host or virtualization host's vSwitch to the
attached virtual servers.
12 multicast-packets-received Long Count Number of multicast packets received by this
virtualization host or virtualization host's vSwitch from
the attached virtual servers.
13 broadcast-packets-sent Long Count Number of broadcast packets sent from this
virtualization host or virtualization host's vSwitch to the
attached virtual servers.

120 HMC Web Services API

 Level 04a

Table 46. Virtualization host (vSwitch) by virtual network metric group (continued)
Pos Metric field name Type Units Description
14 broadcast-packets-received Long Count Number of broadcast packets received by this
virtualization host or virtualization host's vSwitch from
the attached virtual servers.
15 interval-bytes-sent Long Bytes Number of bytes sent by this virtual switch, for the
VLAN specified by vlan-id, over the collection interval.
16 interval-bytes-received Long Bytes Number of bytes received by this virtual switch, for the
VLAN specified by vlan-id, over the collection interval.
17 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this virtual switch,
Second for the VLAN specified by vlan-id, over the collection
interval.
18 bytes-per-second-received Long Bytes per Number of bytes received by this virtual switch, for the
Second VLAN specified by vlan-id, over the collection interval.
19 flags Long Flags indicating the types of metrics that are supported.
The value of this field should be interpreted as a
bitmask. The meaning of each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are supported

Attached virtual server network adapters metric group

This metric group provides metrics for each virtual server's virtual network adapter by virtual network.
Each virtual network adapter may be associated with multiple virtual networks; therefore, there may be
multiple instances of these metrics within the group. These metrics are collected at the virtualization
host's (vSwitch) port level for the attached virtual server virtual network adapter by virtual network.
These metrics are provided from the perspective of the virtualization host or virtualization host's vSwitch
sending data to and receiving data from the virtual server's network adapter. However, there is an
exception to this in the case of the PowerVM virtualization host. In this case, the metrics are collected at
the virtual server's guest O/S level. The metrics are included in this list for consistency, allowing for a
good approximation of the data flowing over the interfaces. Therefore, the metric counters are reversed
from what is provided for the metric in this group. Counters like drops and discards are from the
perspective of the guest O/S for this interface and not the virtualization host.

The resource ID of the associated virtual server's network adapter is provided to allow the client
application to correlate the metrics with a particular virtual server.

Metrics are collected and provided on an interval, and each metric provided is the total cumulative value,
and not a delta.
Metric Group Name
"network-virtual-server-attached-network-adapter"
Collection Interval
30 seconds
Applicable Managed Object Class
"virtual-server"

The following metrics are provided in each entry of this metric group:

Chapter 9. Metric groups 121

 Level 04a

Table 47. Attached virtual server network adapters metric group

Pos Metric field name Type Units Description
1 network-adapter-id String Element identifier of the virtual servers' network
adapter. This value corresponds to the
{network-adapter-id} portion of the URI for the network
adapter. The full URI can be constructed using this
value together with the URI of the parent virtual
server.
2 vlan-id Integer VLAN ID of the virtual network for which metrics are
being provided. This value corresponds to the vlan-id
property of the related Virtual Network object.

There may be cases where this field is 0 when

zManager is unable to determine the per virtual
network metrics for this interface.
3 mac-address String MAC address of this interface.
4 bytes-sent Long Bytes Number of bytes sent to this Virtual Server network
interface for the virtual network.
5 bytes-received Long Bytes Number of bytes received from this Virtual Server
network interface for the virtual network.
6 packets-sent Long Count Number of packets sent on this interface to the Virtual
Server for the virtual network.
7 packets-received Long Count Number of packets received from this Virtual Server
network interface for the virtual network.
8 packets-sent-dropped Long Count Number of packets that were dropped when sending
to this Virtual Server Network interface for the virtual
network.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
9 packets-received-dropped Long Count Number of packets received from this Virtual Server
network interface and for this virtual network that
were dropped.

Packets may be dropped due to conditions related to

resource constraints such as a buffer shortage.
10 packets-sent-discarded Long Count Number of packets that were discarded when sending
to this Virtual Server network interface for this virtual
network.

Packets may be discarded due to errors associated

with the packet, such as malformed packets.
11 packets-received-discarded Long Count Number of packets received from this virtual server
network interface for this virtual network that were
discarded.

Packets may be discarded due to errors associated

with the packet, such as malformed packets
12 multicast-packets-sent Long Count Number of multicast packets sent to this virtual server
network interface for this virtual network.
13 multicast-packets-received Long Count Number of multicast packets received from this virtual
server network interface for this virtual network.
14 broadcast-packets-sent Long Count Number of broadcast packets sent to this virtual server
virtual network interface for this virtual network.

122 HMC Web Services API

 Level 04a

Table 47. Attached virtual server network adapters metric group (continued)
Pos Metric field name Type Units Description
15 broadcast-packets-received Long Count Number of broadcast packets received from this
virtual server virtual network interface for this virtual
network.
16 interval-bytes-sent Long Bytes Number of bytes sent by this network adapter over
the collection interval.
17 interval-bytes-received Long Bytes Number of bytes received by this network adapter
over the collection interval.
18 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this network
Second adapter over the collection interval.
19 bytes-per-second-received Long Bytes per Number of bytes received per second by this network
Second adapter over the collection interval.
20 flags Long Flags indicating the types of metrics that are
supported by this interface. The value of this field
should be interpreted as a bitmask. The meaning of
each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are
supported

Optimizer network metrics

Network metrics are provided for optimizer blades. The following metric groups are provided:
v Optimizer IEDN Virtual Network Interface Metric Group
v Optimizer IEDN Physical Network Adapter Metric Group

Optimizer IEDN virtual network interface metric group

This metric group provides metrics for an optimizer's IEDN attached network interfaces by virtual
network. Currently the following optimizers are supported for this metric group: Datapower.

Metrics are collected and provided on an interval, and each metric provided is the total cumulative value,
and not a delta.
Metric Group Name
"network-optimizer-attached-iedn-interface"
Collection Interval
30 seconds
Applicable Managed Object Class
"blade"

The following metrics are provided in each entry of this metric group:

Chapter 9. Metric groups 123

 Level 04a

Table 48. Optimizer IEDN virtual network interface metric group

Pos Metric field name Type Units Description
1 iedn-interface-id String Element identifier of the optimizer's IEDN interface.
This value corresponds to the {iedn-interface-id}
portion of the URI for the interface. The full URI
can be constructed using this value together with
the URI of the parent blade.
2 vlan-id Integer VLAN ID of the virtual network for which metrics
are being provided. This value corresponds to the
vlan-id property of the related Virtual Network
object.

There may be cases where this field is 0 when

zManager is unable to determine the per virtual
network metrics for this interface.
3 mac-address String MAC address of this interface.
4 bytes-sent Long Count Number of bytes sent from this interface.
5 bytes-received Long Count Number of bytes received by this interface.
6 packets-sent Long Count Number of packets sent from this interface.
7 packets-received Long Count Number of packets received by this interface.
8 packets-sent-dropped Long Count Number of packets that were dropped when
sending to this Virtual Server Network interface for
the virtual network.

Packets may be dropped due to conditions related

to resource constraints such as a buffer shortage.
9 packets-received-dropped Long Count Number of packets received by this interface that
were dropped.

Packets may be dropped due to conditions related

to resource constraints such as a buffer shortage.
10 packets-sent-discarded Long Count Number of packets that were discarded when
sending from this interface.

Packets may be discarded due to errors associated

with the packet, such as malformed packets.
11 packets-received-discarded Long Count Number of packets received by this interface that
were discarded.

Packets may be discarded due to errors associated

with the packet, such as malformed packets.
12 multicast-packets-sent Long Count Number of multicast packets sent from this
interface.
13 multicast-packets-received Long Count Number of multicast packets received by this
interface
14 broadcast-packets-sent Long Count Number of broadcast packets sent from this
interface.
15 broadcast-packets-received Long Count Number of broadcast packets received to this
interface.
16 interval-bytes-sent Long Bytes Number of bytes sent by this interface over the
collection interval.
17 interval-bytes-received Long Bytes Number of bytes received by this interface over the
collection interval

124 HMC Web Services API

 Level 04a

Table 48. Optimizer IEDN virtual network interface metric group (continued)
Pos Metric field name Type Units Description
18 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this interface
Second over the collection interval.
19 bytes-per-second-received Long Bytes per Number of bytes received per second by this
Second interface over the collection interval.
20 flags Long Flags indicating each types of metrics are
supported. The value of this field should be
interpreted as a bitmask. The meaning of each bit is
as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are
supported

Optimizer IEDN physical network adapter metric group

This metric group provides metrics for an optimizer's IEDN attached network interfaces. Currently the
following optimizers are supported for this metric group: Datapower.

Metrics are collected and provided on an interval, and each metric provided is the total cumulative value,
and not a delta.
Metric Group Name
"optimizer-physical-network-adapter"
Collection Interval
30 seconds
Applicable Managed Object Class
"blade"

This metric collection provides metrics for an optimizer's physical network adapters.
Table 49. Optimizer IEDN physical network adapter metric group
Pos Metric field name Type Units Description
1 network-adapter-id String The network-adapter-id is the name of the
optimizer's physical network adapter.

For the DataPower® optimizer, there are two physical

network interfaces. For example, names are
commonly "eth7" and "eth9".
2 mac-address String MAC address of this interface
3 bytes-sent Long Count Number of bytes sent from this interface.
4 bytes-received Long Count Number of bytes received by this interface
5 packets-sent Long Count Number of packets sent from this interface
6 packets-received Long Count Number of packets received by this interface.
7 packets-sent-dropped Long Count Number of packets that were dropped when sending
from this interface.
8 packets-received-dropped Long Count Number of packets received by this interface that
were dropped.

Chapter 9. Metric groups 125

 Level 04a

Table 49. Optimizer IEDN physical network adapter metric group (continued)
Pos Metric field name Type Units Description
9 packets-sent-discarded Long Count Number of packets that were discarded when
sending from this interface.

Packets may be discarded due to errors associated

with the packet, such as malformed packets.
10 packets-received-discarded Long Count Number of packets received by this interface that
were discarded.

Packets may be discarded by the virtual or physical

due to errors associated with the packet, such as
malformed packets.
11 multicast-packets-sent Long Count Number of multicast packets sent from this interface.
12 multicast-packets-received Long Count Number of multicast packets received by this
interface.
13 broadcast-packets-sent Long Count Number of broadcast packets sent from this
interface.
14 broadcast-packets-received Long Count Number of broadcast packets received by this
interface.
15 interval-bytes-sent Long Bytes Number of bytes sent by this network adapter over
the collection interval.
16 interval-bytes-received Long Bytes Number of bytes received by this network adapter
over the collection interval.
17 bytes-per-second-sent Long Bytes per Number of bytes received per second by this
Second network adapter over the collection interval.
18 bytes-per-second-received Long Bytes per Number of bytes sent per second by this network
Second adapter over the collection interval.
19 flags Long Flags indicating the types of metrics that are
reported by this uplink. The value of this field
should be interpreted as a bitmask. The meaning of
each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are
supported

Network adapter port metric group

OSA and RoCE network adapters have up to two physical ports that connect to the network. Metrics are
collected from these ports on a DPM enabled system and provided to the user. This metrics group will
contain metrics data representing metrics for one physical port. Metrics are collected and provided on an
interval, and each metric provided is the total cumulative value, and not a delta.
Metric Group Name
"network-physical-adapter-port"
Collection Interval
30 seconds
Applicable Managed Object Class
"adapter"
126 HMC Web Services API
 Level 04a

The following metrics are provided in each entry of this metric group:
Table 50. Network adapter port metric group
Pos Metric field name Type Units Description
1 network-port-id Integer Numerical value corresponding to the network
adapter's physical port. For OSA adapters, this
value can be either 0 or 1, and for RoCE
adapters, this value can be 1 or 2. To get more
information about the physical port, a URI can
be constructed using this value together with
the target adapter-id:
/api/adapters/{adapter-id}/network-ports/
{network-port-id}
2 bytes-sent Long Bytes Number of bytes this physical port sent out to
the attached network.
3 bytes-received Long Bytes Number of unicast packets this physical port
received from the attached network.
4 packets-sent Long Count Number of unicast packets this physical port
sent out to the attached network.
5 packets-received Long Count Number of unicast packets this physical port
received from the attached network.
6 packets-sent-dropped Long Count Number of packets that were dropped when
this physical port was sending them out to the
attached network.

Packets may be dropped due to conditions

related to resource constraints such as a buffer
shortage.
7 packets-received-dropped Long Count Number of packets that were dropped when
this physical port was receiving them from the
attached network.

Packets may be dropped due to conditions

related to resource constraints such as a buffer
shortage.
8 packets-sent-discarded Long Count Number of packets that were discarded when
this physical port was sending them out to the
attached network.

Packets may be discarded due to errors such as

malformed packets.
9 packets-received-discarded Long Count Number of packets that were discarded when
this physical port was receiving them from the
attached network.

Packets may be discarded due to errors such as

malformed packets.
10 multicast-packets-sent Long Count Number of multicast packets this physical port
sent out to the attached network.
11 multicast-packets-received Long Count Number of multicast packets this physical port
received from the attached network.
12 broadcast-packets-sent Long Count Number of broadcast packets this physical port
sent out to the attached network.
13 broadcast-packets-received Long Count Number of broadcast packets this physical port
received from the attached network.

Chapter 9. Metric groups 127

 Level 04a

Table 50. Network adapter port metric group (continued)

Pos Metric field name Type Units Description
14 interval-bytes-sent Long Bytes Number of bytes sent by this physical port
over the collection interval.
15 interval-bytes-received Long Bytes Number of bytes received by this physical port
over the collection interval.
16 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this
second physical port over the collection interval.
17 bytes-per-second-received Long Bytes per Number of bytes per second received by this
Second physical port over the collection interval.
18 utilization Long Percentage Link utilization expressed as usage percentage
of overall link bandwidth.
19 mac-address String The MAC address of this uplink, if known. If it
is not known, then "N/A".
20 flags Long Flags indicating the types of metrics that are
supported by this interface. The value of this
field should be interpreted as a bitmask. The
meaning of each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 - Packet counts are supported
v 0x08 - Drop counts are supported
v 0x10 - Discard counts are supported
v 0x20 - Multicast counts are supported
v 0x40 - Broadcast counts are supported
v 0x80 - Interval bytes sent and received are
supported

Network interface metric group

This metric group reports metrics for NICs on a DPM enabled system. NICs are network resources
associated with DPM partitions. Only NICs that are activated will report metric data. This metrics group
will contain metrics data representing metrics for one NIC. Metrics are collected and provided on an
interval, and each metric provided is the total cumulative value, and not a delta.
Metric Group Name
"partition-attached-network-interface"
Collection Interval
30 seconds
Applicable Managed Object Class
"nic"

The following metrics are provided in each entry of this metric group:

128 HMC Web Services API

 Level 04a

Table 51. Network interface metric group

Pos Metric field name Type Units Description
1 partition-id String The unique identifier for the partition that owns the
(36) NIC whose metric is contained within this metric
group. To get information about the partition, the
URI can be constructed using partition-id:
/api/partitions/{partition-id}

To get information about the NIC, the URI can be

constructed using the partition-id value together
with the target nic-id:
/api/partitions/{partition-id}/nics/
{nic-id}
2 bytes-sent Long Bytes Number of bytes this network adapter sent out to
the attached network.
3 bytes-received Long Bytes Number of bytes this network adapter received
from the attached network.
4 packets-sent Long Count Number of unicast packets this network adapter
sent out to the attached network.
5 packets-received Long Count Number of unicast packets this network adapter
received from the attached network.
6 packets-sent-dropped Long Count Number of packets that were dropped when this
network adapter was sending them out to the
attached network.

Packets may be dropped due to conditions related

to resource constraints such as a buffer shortage.
7 packets-received-dropped Long Count Number of packets that were dropped when this
network adapter was receiving them from the
attached network.

Packets may be dropped due to conditions related

to resource constraints such as a buffer shortage.
8 packets-sent-discarded Long Count Number of packets that were discarded when this
network adapter was sending them out to the
attached network.

Packets may be discarded due to errors such as

malformed packets.
9 packets-received-discarded Long Count Number of packets that were discarded when this
network adapter was receiving them from the
attached network.

Packets may be discarded due to errors such as

malformed packets.
10 multicast-packets-sent Long Count Number of multicast packets this network adapter
sent out to the attached network.
11 multicast-packets-received Long Count Number of multicast packets this network adapter
received from the attached network.
12 broadcast-packets-sent Long Count Number of broadcast packets this network adapter
sent out to the attached network.
13 broadcast-packets-received Long Count Number of broadcast packets this network adapter
received from the attached network.

Chapter 9. Metric groups 129

 Level 04a

Table 51. Network interface metric group (continued)

Pos Metric field name Type Units Description
14 interval-bytes-sent Long Bytes Number of bytes sent by this network adapter over
the collection interval.
15 interval-bytes-received Long Bytes Number of bytes received by this network adapter
over the collection interval.
16 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this network
second adapter over the collection interval.
17 bytes-per-second-received Long Bytes per Number of bytes per second received by this
Second network adapter over the collection interval.
18 flags Long Flags indicating the types of metrics that are
supported by this interface. The value of this field
should be interpreted as a bitmask. The meaning of
each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 - Packet counts are supported
v 0x08 - Drop counts are supported
v 0x10 - Discard counts are supported
v 0x20 - Multicast counts are supported
v 0x40 - Broadcast counts are supported
v 0x80 - Interval bytes sent and received are
supported

Physical switches
The physical switches provide the connectivity between the blades and CPCs in the intraensemble data
network (IEDN).

There are two types of Ethernet switches within each zBX:

v Top-of-Rack Switches (TORs) – A pair of TORs reside in each zBX and act as a primary and backup.
TORs connect the blades in the zBX to Z network interfaces, and to other external networking
equipment, such as routers.
v Ethernet Switch Modules (ESMs) - These switches connect the blades in the zBX to the IEDN and link
the blades to the TORs.

The initial configuration and setup of the physical switches are provided by zManager. Some TOR ports
can be managed by the user from the zManager UI. The ESMs are not accessible for configuration
changes through zManager's external management interfaces.

Metrics are provides for the following TOR port types:

v External - These ports that connect to customer's external network
v IEDN Host – These ports connect to IEDN network adapters, such as OSX.
v ISAOPT - These ports connect to ISAOPT Coordinator.
v BladeCenter ESM Ports – These ports connect to the ESM switches (other than ISAOPT).
v zBX to zBX- These ports connect the TOR in one zBX to the TOR in another zBX.

Metrics are provides for the following ESM port types:

v Uplinks to TOR – These ports connect the ESM to the TOR.
v Blade Ports – These ports connect the ESMs to the Blade network adapters.

Monitoring the physical switches can allow for determining the health and performance of the switches.
For example, metrics such as dropped and discarded packets can affect the over all performance of
workloads flowing through these switches. Bytes transferred metrics for ports provide the ability to
determine bandwidth utilization.

130 HMC Web Services API

 Level 04a

Top-of-rack switch ports metrics

This metric collection group provides metrics for the Top-of-Rack (TOR) switch ports for the TORs in
each zBX.
Metric Group Name
"top-of-rack-switch-ports"
Collection Interval
120 seconds
Applicable Managed Object Class
"zbx"

This metric collection provides metrics for an optimizer's physical network adapters.
Table 52. Top-of-rack switch port metrics group
Pos Metric field name Type Units Description
1 switch-location-info String The location of the switch in the zBX that was set by
zManager.

The switch-location-info is a 4 character cage location

identifier. The first character identifies the zBX rack,
and the remaining characters identify the vertical
location within the rack
2 port-num Integer Switch port number
3 type String v “B” (BladeCenter ESM port): attaches to an ESM
Enum switch.
v “H” (Host port): attaches to network adapters for
the IEDN
v “E” (External port): attaches to external networking
equipment
v “I” (ISAOPT port): for ISAOPT
v “Z” (zBX port): attaches the zBX to another zBX
v “T” (TOR port): attaches to the other TOR switch in
the same zBX
4 remote-partner-info String The remote partner depends upon the port type:
v If type is “Z”: attached to a TOR in another zBX,
this will be the location of the top-of-rack-switch.
v If type is “E”: "N/A"
v If type is “H”: This is the cpc id.pchid of the
attached OSX.
v If type is “B”: The format of the remote-partner-info
is bladecenter chassis-id_ esm location-id The first 4
characters identify the blade center chassis within
this zBX. The last 4 characters identify the ESM
location ID
v If type is “I”: The name of the blade center chassis
containing the ISAOPT blades
v If type is “T”: The name of the other TOR switch.
5 bytes-sent Long Count Number of bytes sent from this port.
6 bytes-received Long Count Number of bytes received to this port.
7 packets-sent Long Count Number of packets sent from this port.
8 packets-received Long Count Number of packets received to this port.
9 packets-sent-dropped Long Count Number of packets that were dropped when sending
from this port.

Chapter 9. Metric groups 131

 Level 04a

Table 52. Top-of-rack switch port metrics group (continued)

Pos Metric field name Type Units Description
10 packets-received-dropped Long Count Number of packets received to this port that were
dropped.
11 packets-sent-discarded Long Count Number of packets that were discarded when sending
from this port. Packets may be discarded due to errors
associated with the packet, such as malformed
packets.
12 packets-received-discarded Long Count Number of packets received by these ports that were
discarded. Packets may be discarded by the virtual or
physical due to errors associated with the packet, such
as malformed packets
13 multicast-packets-sent Long Count Number of multicast packets sent from this port.
14 multicast-packets-received Long Count Number of multicast packets received to this port.
15 broadcast-packets-sent Long Count Number of broadcast packets sent from this port.
16 broadcast-packets-received Long Count Number of broadcast packets received to this port.
17 interval-bytes-sent Long Bytes Number of bytes sent by this switch port over the
collection interval.
18 interval-bytes-received Long Bytes Number of bytes received by this switch port over the
collection interval.
19 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this switch port
Second over the collection interval.
20 bytes-per-second-received Long Bytes per Number of bytes received per second by this switch
Second port over the collection interval.
21 flags Long Flags indicating the types of metrics that are reported
by this uplink. The value of this field should be
interpreted as a bitmask. The meaning of each bit is
as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are
supported

ESM switch port metrics

This metric group provides metrics for the ESM switch ports for each ESM in each zBX.
Metric Group Name
"ethernet-switch-module-ports"
Collection Interval
120 seconds
Applicable Managed Object Class
"zbx"

This metric collection provides metrics for an optimizer's physical network adapters.

132 HMC Web Services API

 Level 04a

Table 53. Optimizer IEDN physical network adapter metric group

Pos Metric field name Type Units Description
1 switch-location-info String The location of the switch in the zBX that was set
by zManager.

The switch-location-info is a 4 character cage

location identifier. The first character identifies the
zBX rack, and the remaining characters identify the
vertical location within the rack.
2 port-num Integer Switch port number
3 type String v “I” (Internal port): This port is connected to a
Enum Blade.
v “E” (External port): This port is connected to a
TOR.
4 remote-partner-info String Information about the remote element connected to
the port. The value depends on the type of the port.
In the case where the port type is:
v If type is “E”: This field is the name of the
top-of-rack-switch connected to this ESM port.
This TOR resides in the same zBX as the ESM.
v If type is “I”: This field is the name of the
attached blade. The blade resides in the same zBX
and blade center chassis as the ESM.
5 bytes-sent Long Count Number of bytes sent from this port.
6 bytes-received Long Count Number of bytes received to this port.
7 packets-sent Long Count Number of packets sent from this port.
8 packets-received Long Count Number of packets received to this port.
9 packets-sent-dropped Long Count Number of packets that were dropped when
sending from this port.
10 packets-received-dropped Long Count Number of packets received to this port that were
dropped.
11 packets-sent-discarded Long Count Number of packets that were discarded when
sending from this port. Packets may be discarded
due to errors associated with the packet, such as
malformed packets.
12 packets-received-discarded Long Count Number of packets received by these ports that
were discarded. Packets may be discarded by the
virtual or physical due to errors associated with the
packet, such as malformed packets.
13 multicast-packets-sent Long Count Number of multicast packets sent from this port.
14 multicast-packets-received Long Count Number of multicast packets received to this port.
15 broadcast-packets-sent Long Count Number of broadcast packets sent from this port.
16 broadcast-packets-received Long Count Number of broadcast packets received to this port.
17 interval-bytes-sent Long Bytes Number of bytes sent by this switch port over the
collection interval.
18 interval-bytes-received Long Bytes Number of bytes received by this switch port over
the collection interval.
19 bytes-per-second-sent Long Bytes per Number of bytes sent per second by this switch
Second port over the collection interval.
20 bytes-per-second-received Long Bytes per Number of bytes received per second by this switch
Second port over the collection interval.

Chapter 9. Metric groups 133

 Level 04a

Table 53. Optimizer IEDN physical network adapter metric group (continued)
Pos Metric field name Type Units Description
21 flags Long Flags indicating the types of metrics that are
reported by this uplink. The value of this field
should be interpreted as a bitmask. The meaning of
each bit is as follows:
v 0x02 - Byte counts are supported
v 0x04 – Packet counts are supported
v 0x08 – Drop counts are supported
v 0x10 – Discard counts are supported
v 0x20 – Multicast counts are supported
v 0x40 – Broadcast counts are supported
v 0x80 – Interval bytes sent and received are
supported

134 HMC Web Services API

 Level 04a

Part 3. CPC management

Topics in this part describe CPC management.

Topics covered in this part are:

v Chapter 10, “Dynamic Partition Manager (DPM),” on page 137
v Chapter 11, “Core IBM Z resources,” on page 473
v Chapter 12, “Energy management,” on page 817

© Copyright IBM Corp. 2017, 2018 135

 Level 04a

136 HMC Web Services API

 Level 04a

Chapter 10. Dynamic Partition Manager (DPM)

IBM Dynamic Partition Manager (DPM) expands on the PR/SM (Processor Resource/Systems Manager™)
concept of logical partitions and provides a simplified, consumable, enhanced user experience reducing
the barriers of adoption for new and existing clients.

IBM DPM seamlessly integrates platform I/O resource management, server, network and storage resource
provisioning, dynamic resource adjustments and resource monitoring. This enhanced, and encapsulated
management through the HMC as the single management end-point eliminates the need for special skills
to operate the integrated Z platform and its hardware and virtual infrastructure. The HMC Web Services
API enables customers, or IBM and third-party data center management tooling respectively to automate
all of the IBM DPM tasks, for example, to discover, manage, and monitor resources, and to provide event
notifications.

The DPM APIs provide access to and control of the following HMC/SE objects:
v Partition object
v Virtual Function element object
v NIC element object
v HBA element object
v Adapter object
v Network Port element object
v Storage Port element object
v Virtual Switch object
v Capacity Group element object
v FICON Storage Configuration objects:
Storage Site object
Storage Fabric object
Storage Switch object
Storage Subsystem object
Storage Control Unit object
v Storage Group object

| FICON storage configuration

| A number of the classes defined in the Dynamic Partition Manager chapter are interrelated and in their
| entirety, define the FICON storage configuration as seen by a single CPC. This configuration is used by
| the CPC to understand the paths that connect their storage adapters to the storage resources that are
| needed by the partitions running in that CPC.

| The following diagram illustrates the major components of a FICON configuration.

|

© Copyright IBM Corp. 2017, 2018 137

 Level 04a

|
| v FICON storage resources are organized into storage sites. The primary site is the one in which the CPC
| (System "M01" in the diagram) is located. It likely also includes sets of storage switches and storage
| subsystems that are also local to the CPC. The primary site will always exist. Optionally, a second
| alternate site can also exist. Alternate sites are typically remote to the CPC, and often used for
| redundancy. In the diagram, the primary site is labeled "New York" and the alternate site is labeled
| "New Jersey".
| v Storage subsystems represent the physical storage units. They are physically connected (cabled) to a set
| of storage switches or directly to a set of CPC storage adapters. Storage subsystems are subdivided
| into logical control units, which provide access to a subset of a subsystem's storage resources. Storage
| control units are logically connected to CPC storage adapters, optionally through one or two storage
| switches. In the diagram, storage subsystems named "DS8870 A" and "DS8886 A" are located in the
| primary "New York" site and storage subsystems named "DS8870 B" and "DS8886 B" are located in the
| alternate "New Jersey" site.
| v Storage switches are optionally used within a CPC storage adapter to storage control unit connection.
| The switch that is connected to the CPC storage adapter is referred to as the "entrance" switch. The
| switch that is connected to the storage subsystem is referred to as the "exit" switch. The entrance and
| exit switches can be the same, which means there is exactly one switch connecting the adapter and
| control unit. If the entrance and exit switches are different, there are two switches connecting the
| adapter and control unit, and they are referred to as being in a cascaded switch configuration. In a
| cascaded configuration, the entrance switch will be in the primary site and the exit switch will be in
| the alternate site. A storage switch exists in exactly one storage site and in exactly one storage fabric. In
| the diagram, storage switches 10 and 20 exist in the primary "New York" site. The CPC is connected
| through those switches to the "DS8870 A" and "DS8886 A" storage subsystems. Switches 11 and 21 exist
| in the alternate "New Jersey" site. The CPC is connected in cascaded configurations through those
| switches to the "DS8870 B" and "DS8886 B" storage subsystems.
| v The set of all storage switches that are interconnected defines a storage fabric. In a multi-site
| configuration, switches from both sites are interconnected, therefore in such configurations, a fabric will
| span multiple sites. In the diagram, storage switches 10 and 11 are interconnected and define storage
| fabric "Fabric A". Storage switches 20 and 21 define storage fabric "Fabric B".

| It is important to understand that a FICON configuration is scoped to a single CPC, and represents that
| CPC’s view of a set of storage resources. A second CPC’s FICON configuration may include objects that
| represent the same physical or logical entities, but they will be returned to an API client as separate
| objects. The data models for those objects provide no intrinsic way to determine those objects represent
| the same physical or logical entity. Correlation is possible only if the configurations are created using
| names or other identifiers that are the same.

138 HMC Web Services API

 Level 04a

Operations summary
Following are the operations summaries for each of the Dynamic Partition Manager (DPM) objects.

Partition operations summary

The following table provides an overview of the operations provided for Partition objects.
Table 54. DPM - Partition: operations summary
Operation name HTTP method and URI path
“List Partitions of a CPC” on GET /api/cpcs/{cpc-id}/partitions
page 164
“List Permitted Partitions” on GET /api/console/operations/list-permitted-partitions
page 167
“Create Partition” on page 170 POST /api/cpcs/{cpc-id}/partitions
“Delete Partition” on page 175 DELETE /api/partitions/{partition-id}
“Delete Partition POST /api/partitions/{partition-id}/operations/async-delete
Asynchronously” on page 177
“Get Partition Properties” on GET /api/partitions/{partition-id}
page 179
“Update Partition Properties” on POST /api/partitions/{partition-id}
page 182
“Update Partition Properties POST /api/partitions/{partition-id}/operations/async-update
Asynchronously” on page 186
“Start Partition” on page 190 POST /api/partitions/{partition-id}/operations/start
“Stop Partition” on page 193 POST /api/partitions/{partition-id}/operations/stop
“Dump Partition” on page 195 POST /api/partitions/{partition-id}/operations/scsi-dump
| “Start Dump Program” on page POST /api/partitions/{partition-id}/operations/start-dump-program
| 199
“Perform PSW Restart” on page POST /api/partitions/{partition-id}/operations/psw-restart
203
“Create Virtual Function” on POST /api/partitions/{partition-id}/virtual-functions
page 205
“Delete Virtual Function” on page DELETE /api/partitions/{partition-id}/virtual-functions/{virtual-
208 function-id}
“Get Virtual Function Properties” GET /api/partitions/{partition-id}/virtual-functions/{virtual-function-
on page 209 id}
“Update Virtual Function POST /api/partitions/{partition-id}/virtual-functions/{virtual-function-
Properties” on page 211 id}
“Create NIC” on page 213 POST /api/partitions/{partition-id}/nics
“Delete NIC” on page 217 DELETE /api/partitions/{partition-id}/nics/{nic-id}
“Get NIC Properties” on page 218 GET /api/partitions/{partition-id}/nics/{nic-id}
“Update NIC Properties” on page POST /api/partitions/{partition-id}/nics/{nic-id}
220
“Increase Crypto Configuration” POST /api/partitions/{partition-id}/operations/increase-crypto-
on page 223 configuration
“Change Crypto Domain POST /api/partitions/{partition-id}/operations/change-crypto-domain-
Configuration” on page 226 configuration

Chapter 10. Dynamic Partition Manager (DPM) 139

 Level 04a

Table 54. DPM - Partition: operations summary (continued)

Operation name HTTP method and URI path
“Decrease Crypto Configuration” POST /api/partitions/{partition-id}/operations/decrease-crypto-
on page 228 configuration
“Mount ISO Image” on page 231 POST /api/partitions/{partition-id}/operations/mount-iso-image
“Unmount ISO Image” on page POST /api/partitions/{partition-id}/operations/unmount-iso-image
233
| “Attach Storage Group to POST /api/partitions/{partition-id}/operations/attach-storage-group
| Partition” on page 234
| “Detach Storage Group from POST /api/partitions/{partition-id}/operations/detach-storage-group
| Partition” on page 237
“Create HBA” on page 239 POST /api/partitions/{partition-id}/hbas
“Delete HBA” on page 241 DELETE /api/partitions/{partition-id}/hbas{hba-id}
“Update HBA Properties” on POST /api/partitions/{partition-id}/hbas/{hba-id}
page 243
“Get HBA Properties” on page GET /api/partitions/{partition-id}/hbas/{hba-id}
245
“Reassign Storage Adapter Port” POST /api/partitions/{partition-id}/hbas/{hba-id}/operations/reassign-
on page 247 storage-adapter-port
“Send OS Command” on page POST /api/partitions/{partition-id}/operations/send-os-cmd
249
“Open OS Message Channel” on POST /api/partitions/{partition-id}/operations/open-os-message-channel
page 251
“List OS Messages of a Partition” GET /api/partitions/{partition-id}/operations/list-os-messages
on page 253
“Get ASCII Console WebSocket POST /api/partitions/{partition-id}/operations/get-ascii-console-
URI” on page 256 websocket-uri

Table 55. DPM - Partition: URI variables

Variable Description
{cpc-id} Object ID of the CPC object.
{partition-id} Object ID of the Partition object.
{virtual-function-id} Element ID of the Virtual Function element object.
{nic-id} Element ID of the NIC element object.
{hba-id} Element ID of the HBA element object.

Adapter operations summary

The following table provides an overview of the operations provided for Adapter objects.
Table 56. DPM - Adapter: operations summary
Operation name HTTP method and URI path
“List Adapters of a CPC” on page GET /api/cpcs/{cpc-id}/adapters
273
“Get Adapter Properties” on page GET /api/adapters/{adapter-id}
275
“Update Adapter Properties” on POST /api/adapters/{adapter-id}}
page 277

140 HMC Web Services API

 Level 04a

Table 56. DPM - Adapter: operations summary (continued)

Operation name HTTP method and URI path
“Change Crypto Type” on page POST /api/adapters/{adapter-id}/operations/change-crypto-type
279
“Create Hipersocket” on page 282 POST /api/cpcs/{cpc-id}/adapters
“Delete Hipersocket” on page 284 DELETE /api/adapters/{adapter-id}
“Get Partitions Assigned to GET /api/adapters/{adapter-id}/operations/get-partitions-assigned-to-
Adapter” on page 285 adapter
“Get Network Port Properties” on GET /api/adapters/{adapter-id}/network-ports/{network-port-id}
page 287
“Update Network Port POST /api/adapters/{adapter-id}/network-ports/{network-port-id}
Properties” on page 289
“Get Storage Port Properties” on GET /api/adapters/{adapter-id}/storage-ports/{storage-port-id}
page 291
“Update Storage Port Properties” POST /api/adapters/{adapter-id}/storage-ports/{storage-port-id}
on page 292
| Change Adapter Type POST /api/adapters/{adapter-id}/operations/change-adapter-type

Table 57. DPM - Adapter: URI variables

Variable Description
{cpc-id} Object ID of a CPC object.
{adapter-id} Object ID of an Adapter object.
{network-port-id} Element ID of a Network Port element object.
{storage-port-id} Element ID of a Storage Port element object.

Virtual Switch operations summary

The following table provides an overview of the operations provided for Virtual Switch objects.
Table 58. DPM - Virtual Switch: operations summary
Operation name HTTP method and URI path
“List Virtual Switches of a CPC” GET /api/cpcs/{cpc-id}/virtual-switches
on page 299
“Get Virtual Switch Properties” GET /api/virtual-switches/{vswitch-id}
on page 301
“Get Connected VNICs of a GET /api/virtual-switches/{vswitch-id}/operations/get-connected-vnics
Virtual Switch” on page 303
“Update Virtual Switch POST /api/virtual-switches/{vswitch-id}
Properties” on page 304

Table 59. DPM - Virtual Switch: URI variables

Variable Description
{cpc-id} Object ID of the CPC object
{vswitch-id} Object ID of the Virtual Switch object

Chapter 10. Dynamic Partition Manager (DPM) 141

 Level 04a

Capacity Group operations summary

The following table provides an overview of the operations provided for Capacity Group objects.
Table 60. DPM - Capacity Group: operations summary
Operation name HTTP method and URI path
“List Capacity Groups of a CPC” on page GET /api/cpcs/{cpc-id}/capacity-groups
308
“Create Capacity Group” on page 310 POST /api/cpcs/{cpc-id}/capacity-groups
“Delete Capacity Group” on page 313 DELETE /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}
“Get Capacity Group Properties” on page GET /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}
315
“Add Partition to Capacity Group” on POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}/
page 316 operations/add-partition
“Remove Partition from Capacity Group” POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}/
on page 319 operations/remove-partition
“Update Capacity Group Properties” on POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}
page 321

Table 61. DPM - Capacity Group: URI variables

Variable Description
{cpc-id} Object ID of a CPC object
{capacity-group-id} Element ID of the Capacity Group element object

| Storage Site operations summary

| The following table provides an overview of the operations provided for Storage Site objects.
| Table 62. DPM - Storage Site: operations summary
| Operation name HTTP method and URI path
| “List Storage Sites” on page 324 GET /api/storage-sites
| “Create Storage Site” on page 327 POST /api/storage-sites
| “Delete Storage Site” on page 330 DELETE /api/storage-sites
| “Get Storage Site Properties” on page 331 GET /api/storage-sites/{storage-site-id}
| “Update Storage Site Properties” on page POST /api/storage-sites/{storage-site-id}
| 333
|
| Table 63. DPM - Storage Site: URI variables
| Variable Description
| {storage-site-id} Object ID of a Storage Site object
|

| Storage Fabric operations summary

| The following table provides an overview of the operations provided for Storage Fabric objects.
| Table 64. DPM - Storage Fabric: operations summary
| Operation name HTTP method and URI path
| “List Storage Fabrics” on page 337 GET /api/storage-fabrics
| “Create Storage Fabric” on page 339 POST /api/storage-fabrics

142 HMC Web Services API

 Level 04a

| Table 64. DPM - Storage Fabric: operations summary (continued)

| Operation name HTTP method and URI path
| “Delete Storage Fabric” on page 342 DELETE /api/storage-fabrics/{storage-fabric-id}
| “Get Storage Fabric Properties” on page GET /api/storage-fabrics/{storage-fabric-id}
| 343
| “Update Storage Fabric Properties” on POST /api/storage-fabrics/{storage-fabric-id}
| page 344
|
| Table 65. DPM - Storage Fabric: URI variables
| Variable Description
| {storage-fabric-id} Object ID of a Storage Fabric object
|

| Storage Switch operations summary

| The following table provides an overview of the operations provided for Storage Switch objects.
| Table 66. DPM - Storage Switch: operations summary
| Operation name HTTP method and URI path
| “List Storage Switches of a Storage Site” GET /api/storage-sites/{storage-site-id}/storage-switches
| on page 348
| “List Storage Switches of a Storage GET /api/storage-fabrics/{storage-fabric-id}/storage-switches
| Fabric” on page 351
| “Define Storage Switch” on page 353 POST /api/console/operations/define-storage-switch
| “Undefine Storage Switch” on page 355 POST /api/storage-switches/{storage-switch-id}/operations/undefine
| “Get Storage Switch Properties” on page GET /api/storage-switches/{storage-switch-id}
| 357
| “Update Storage Switch Properties” on POST /api/storage-switches/{storage-switch-id}
| page 358
| “Move Storage Switch to Storage Site” on POST /api/storage-switches/{storage-switch-id}/operations/move-
| page 360 storage-site
| “Move Storage Switch to Storage Fabric” POST /api/storage-switches/{storage-switch-id}/operations/move-
| on page 362 storage-fabric
|
| Table 67. DPM - Storage Switch: URI variables
| Variable Description
| {storage-site-id} Object ID of a Storage Site object
| {storage-fabric-id} Object ID of a Storage Fabric object
| {storage-switch-id} Object ID of a Storage Switch object
|

| Storage Subsystem operations summary

| The following table provides an overview of the operations provided for Storage Subsystem objects.
| Table 68. DPM - Storage Subsystem: operations summary
| Operation name HTTP method and URI path
| “List Storage Subsystems of a Storage GET /api/storage-sites/{storage-site-id}/storage-subsystems
| Site” on page 366
| “Define Storage Subsystem” on page 369 POST /api/console/operations/define-storage-subsystem

Chapter 10. Dynamic Partition Manager (DPM) 143

 Level 04a

| Table 68. DPM - Storage Subsystem: operations summary (continued)

| Operation name HTTP method and URI path
| “Undefine Storage Subsystem” on page POST /api/storage-subsystems/{storage-subsystem-id}/operations/
| 371 undefine
| “Get Storage Subsystem Properties” on GET /api/storage-subsystems/{storage-subsystem-id}
| page 372
| “Update Storage Subsystem Properties” POST /api/storage-subsystems/{storage-subsystem-id}
| on page 374
| “Move Storage Subsystem to Storage POST /api/storage-subsystems/{storage-subsystem-id}/operations/
| Site” on page 376 move-storage-site
| “Add Connection Endpoint” on page 378 POST /api/storage-subsystems/{storage-subsystem-id}/operations/
| add-connection-endpoint
| “Remove Connection Endpoint” on page POST /api/storage-subsystems/{storage-subsystem-id}/operations/
| 380 remove-connection-endpoint
|
| Table 69. DPM - Storage Subsystem: URI variables
| Variable Description
| {storage-site-id} Object ID of a Storage Site object
| {storage-subsystem-id} Object ID of a Storage Subsystem object
|

| Storage Control Unit operations summary

| The following table provides an overview of the operations provided for Storage Control Unit objects.
| Table 70. DPM - Storage Control Unit: operations summary
| Operation name HTTP method and URI path
| “List Storage Control Units of a Storage GET /api/storage-subsystems/{storage-subsystem-id}/storage-
| Subsystem” on page 386 control-units
| “Define Storage Control Unit” on page POST /api/storage-subsystems/{storage-subsystem-id}/operations/
| 388 define-storage-control-unit
| “Undefine Storage Control Unit” on page POST /api/storage-control-units/{storage-control-unit-id}/
| 390 operations/undefine
| “Get Storage Control Unit Properties” on GET /api/storage-control-units/{storage-control-unit-id}
| page 392
| “Update Storage Control Unit Properties” POST /api/storage-control-units/{storage-control-unit-id}
| on page 394
| “Add Volume Range” on page 396 POST /api/storage-control-units/{storage-control-unit-id}/
| operations/add-volume-range
| “Remove Volume Range” on page 398 POST /api/storage-control-units/{storage-control-unit-id}/
| operations/remove-volume-range
| “Create Storage Path” on page 400 POST /api/storage-control-units/{storage-control-unit-id}/storage-
| paths
| “Delete Storage Path” on page 402 DELETE /api/storage-control-units/{storage-control-unit-id}/
| storage-paths/{storage-path-id}
| “Get Storage Path Properties” on page GET /api/storage-control-units/{storage-control-unit-id}/storage-
| 404 paths/{storage-path-id}
| “Update Storage Path Properties” on POST /api/storage-control-units/{storage-control-unit-id}/storage-
| page 405 paths/{storage-path-id}
|

144 HMC Web Services API

 Level 04a

| Table 71. DPM - Storage Control Unit: URI variables

| Variable Description
| {storage-subsystem-id} Object ID of a Storage Subsystem object
| {storage-path-id} Element ID of the Storage Path object
| {storage-control-unit-id} Object ID of a Storage Control Unit object
|

| Storage Group operations summary

| The following table provides an overview of the operations provided for Storage Group objects.
| Table 72. DPM - Storage Group: operations summary
| Operation name HTTP method and URI path
| “List Storage Groups” on page 424 GET /api/storage-groups/
| “Create Storage Group” on page 426 POST /api/storage-groups/
| “Delete Storage Group” on page 430 POST /api/storage-groups/{storage-group-id}
| “Get Storage Group Properties” on page GET /api/storage-groups/{storage-group-id}
| 433
| “Modify Storage Group Properties” on POST /api/storage-groups/{storage-group-id}/operations/modify
| page 435
| “Add Candidate Adapter Ports to an FCP POST /api/storage-groups/{storage-group-id}/operations/add-
| Storage Group” on page 443 candidate-adapter-ports
| “Remove Candidate Adapter Ports from POST /api/storage-groups/{storage-group-id}/operations/remove-
| an FCP Storage Group” on page 446 candidate-adapter-ports
| “List Storage Volumes of a Storage GET /api/storage-groups/{storage-group-id}/storage-volumes
| Group” on page 448
| “Get Storage Volume Properties” on page GET /api/storage-groups/{storage-group-id}/storage-
| 451 volumes{storage-volume-id}
| “Fulfill FICON Storage Volume” on page POST /api/storage-groups/{storage-group-id}/storage-volumes/
| 453 {storage-volume-id}/operations/fulfill-ficon-storage-volume
| “Fulfill FCP Storage Volume” on page 456 POST /api/storage-groups/{storage-group-id}/storage-volumes/
| {storage-volume-id}/operations/fulfill-fcp-storage-volume
| “List Virtual Storage Resources of a GET /api/storage-groups/{storage-group-id}/virtual-storage-
| Storage Group” on page 459 resources
| “Get Virtual Storage Resource Properties” GET /api/storage-groups/{storage-group-id}/virtual-storage-
| on page 461 resources/{virtual-storage-resource-id}
| “Update Virtual Storage Resource POST /api/storage-groups/{storage-group-id}/virtual-storage-
| Properties” on page 463 resources/{virtual-storage-resource-id}
| “Get Partitions for a Storage Group” on GET /api/storage-groups/{storage-group-id}/operations/get-
| page 465 partitions
| “Validate LUN Path” on page 467 POST /api/cpcs/{cpc-id}/operations/validate-lun-path
|
| Table 73. DPM - Storage Group: URI variables
| Variable Description
| {storage-group-id} Object ID of a Storage Group object
| {storage-volume-id} Element ID of a Storage Volume element object
| {virtual-storage-resource-id} Element ID of a Virtual Storage Resource element object
| {cpc-id} Object ID of the CPC
|

Chapter 10. Dynamic Partition Manager (DPM) 145

 Level 04a

|
Partition object
The Partition object is central to partition management for IBM Dynamic Partition Manager (DPM). It
stores configuration data and is the focal point for various DPM operations.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
including the operational-status-related properties, with the following class-specific specializations:
Table 74. Partition object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path for a Partition object is of the form
URI /api/partitions/{partition-id}, where {partition-id} is the
value of the object-id property of the Partition object.
parent — String/ The canonical URI path of the hosting CPC object.
URI
class — String The class of the Partition object is "partition".
name (w)(pc) String The name of the partition.
(1-64)
The name must be unique on a hosting CPC. The length and
character requirements on this property are the same as those
described in the “Base managed object properties schema” on page
60.
description (w)(pc) String The description associated with this partition.
(0-1024)
Default: an empty string.

146 HMC Web Services API

 Level 04a

Table 74. Partition object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
status (sc) String The current operational status of the managed resource. Values:
Enum v "communications-not-active" - This status indicates that the
HMC is not communicating with the SE.
v "status-check" - This status indicates that the current status of
the partition is unknown. This state normally indicates a
communication issue between the SE and the CPC.
v "stopped" - The partition is not running on the CPC. If the
partition's reserve-resources property is false, the CPC memory,
processor, and adapter resources defined for the partition are not
currently allocated to it and are thus available for use by other
partitions.
v "terminated" - The partition was previously active on the CPC,
but is no longer executing the operating system because all
processors have been stopped by the operating system via some
in-band action. This status may indicate that the operating
system has been shut down or has “crashed”. This status
represents a condition between "active" and "stopped". Although
the partition is not executing the operating system, all CPC
memory, processor, and adapter resources defined for it remain
allocated to it. The Stop Partition action can be used to release
the partition's non-reserved resources and place it in "stopped"
status.
v "starting" - A transitional status between "stopped" and "active"
indicating that a Start Partition action has been initiated to put
the partition into execution, but processing of that action has not
yet completed.
v "active" - The partition is up and running.
v "stopping" - A transitional status between "active" and "stopped"
indicating that a Stop Partition action has been initiated to stop
execution of the partition and release its non-reserved resources,
but the processing of that action has not yet completed.
v "degraded" - The partition is active and one or more resources of
the partition are in a degraded state and are not available for
use.
v "reservation-error" - The partition's reserve-resources property is
true but one or more resources of the partition are in a degraded
state and are not available for use.
v "paused" - The partition was previously active on the CPC, but it
is not currently executing the operating system because all
processors have been stopped by the user via HMC or SE
actions. Typically, partitions are temporarily placed in this status
as part of performing diagnosis activities on the operating
system in the partition. Although the partition is not currently
executing the operating system, all CPC memory, processor, and
adapter resources defined for it remain allocated to it. The HMC
or SE UI actions can be used to resume execution of the
operating system and place it in "active" status again.
Alternatively, The Stop Partition action can be used to release
the partition's non-reserved resources and place it in "stopped"
status.
additional-status — This property is not provided.

Class specific additional properties

In addition to the properties defined in the base managed object, this object includes the following
additional class-specific properties:

Chapter 10. Dynamic Partition Manager (DPM) 147

 Level 04a

Table 75. Partition object: class specific properties

Name Qualifier Type Description
type — String Enum Defines the type of the partition.

One of the following Values:

v "linux" - the partition is intended for running a Linux
operating system.
v "ssc" - the partition will be running an IBM Secure
Service Container appliance.
v "zvm" - the partition is intended for running a z/VM
operating system.

The "ssc" type is only available with SE Version 2.13.1 or

later that has MCL P00339.304 installed.

Default: "linux"
short-name (w)(pc) String (1-8) The short name must be 1-8 characters long, made up of
uppercase alphanumeric characters, and have an
alphabetic first character. The words PHYSICAL, REC,
SYSTEM, and PRIMnnnn (where nnnn is a 4-digit
number) are reserved and cannot be used. The short
name is provided to the operating system running in the
partition, for example by the STORE SYSTEM
INFORMATION instruction.

Default: Auto-generated

Constraint: This property can only be updated when the

partition's status is "stopped".
partition-id (w)(pc) String (2) The partition ID must be a two character hex number
from 00 - 7F.

When autogenerate-partition-id is true:

v The user will not be able to set the value of
partition-id, either on Create Partition or Update
Partition Properties.
v The value can be either null when the partition is not
active and reserve-resources is false, or a value in the
defined range.
v A non-conflicting value is automatically generated and
assigned when the partition is started or when
reserve-resources is set to true. It is cleared when the
partition is stopped and reserve-resources is set to
false.

When autogenerate-partition-id is false:

v The user must specify a non-conflicting value of
partition-id on Create Partition, and can then later
change it via Update Partition Properties.
v The value specified by the user must be in the defined
range.
v The value remains assigned to the partition unless
changed by the user, or cleared as a consequence of
changing the value of autogenerate-partition-id to true.

Default: null

Constraint: This property can only be updated when the

partition's status is "stopped".

148 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
autogenerate- (w)(pc) Boolean Indicates if the partition-id is to be auto-generated.
partition-id
Default: true

Constraint: This property can only be updated when the

partition's status is "stopped".
os-name (pc) String (0-8) An operating system provided value, used to identify the
operating system instance. The format of the value is
operating system dependent. If not provided by the
operating system or if the partition's status is "stopped",
an empty string is returned.
os-type (pc) String (0-8) A human readable form of the operating system provided
value for the type of the operating system active in this
partition. If not provided by the operating system or if
the partition status is "stopped", an empty string is
returned.
os-version (pc) String (0-32) A human readable form of the operating system provided
value for the version of the operating system active in
this partition. If not provided by the operating system or
if the partition status is "stopped", an empty string is
returned.
reserve-resources (w)(pc) Boolean If true, resource reservation is enabled for this partition,
and all physical resources backing the virtual resources
configured for this partition are allocated and reserved,
even when the partition is in "stopped" state. This
guarantees that the partition start will not fail due to
non-availability of resources.

Default: false
degraded-adapters (pc) Array of String/ Array of URIs referring to I/O adapters (NIC, HBA,
URI virtual function, crypto adapter) attached to the partition
that are degraded. Only used if status property of
partition is "degraded". If the partition has no degraded
adapters, the array is empty.
processor-mode (w)(pc) String Enum Defines how processors are allocated to the partition.

One of the following values:

v "dedicated" - All processors in the partition are to be
exclusively available to this specific partition.
v "shared" - All processors in the partition are to be
shareable across partitions.

Default: shared

Constraint: This property can only be updated when the

partition's status is "stopped".
cp-processors (w)(pc) Integer Defines the number of general purpose processors (CP) to
be allocated for the partition.

Default: 0
Note: Exactly one of the cp-processors and ifl-processors
must have a value other than 0.

Chapter 10. Dynamic Partition Manager (DPM) 149

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
ifl-processors (w)(pc) Integer Defines the number of IFL processors to be allocated for
the partition.

Default: 0
Note: Exactly one of the cp-processors and ifl-processors
must have a value other than 0.
ifl-absolute-processor- (w)(pc) Boolean Indicates if absolute processor capping for ifl-processors
capping is enforced. Absolute processor capping prevents this
partition from using any more than the specified number
of physical processors.

Default: false
cp-absolute-processor- (w)(pc) Boolean Indicates if absolute processor capping for cp-processors
capping is enforced. Absolute processor capping prevents this
partition from using any more than the specified number
of physical processors.

Default: false
ifl-absolute-processor- (w)(pc) Float The amount of absolute capping applied to ifl-processors.
capping-value
Valid range: 0.01-255.00 in increments of 0.01.

Default: 1.0
cp-absolute-processor- (w)(pc) Float The amount of absolute capping applied to cp-processors.
capping-value
Valid range: 0.01-255.00 in increments of 0.01.

Default: 1.0
ifl-processing-weight- (w)(pc) Boolean Whether the processing weight for Integrated Facility for
capped Linux (IFL) processors is a limit or a target.

true: Indicates the IFL processor processing weight for the

partition is capped. It represents the partition's maximum
share of ifl-processors resources, regardless of the
availability of excess IFL processor resources.

false: Indicates the IFL processor processing weight for

the partition is not capped. It represents the share of
ifl-processors resources guaranteed to a partition when
all IFL processor resources are in use. Otherwise, when
excess IFL processor resources are available, the partition
can use them if necessary.

Default: false

150 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
cp-processing-weight- (w)(pc) Boolean Indicates whether the processing weight for general
capped purpose processors is a limit or a target.

true: Indicates that the general purpose processor

processing weight for the partition is capped. It
represents the partition's maximum share of
cp-processors.

false: Indicates that the general purpose processor

processing weight for the partition is not capped. It
represents the share of processor resources guaranteed to
a partition when all general purpose processor resources
are in use. Otherwise, when excess general purpose
processor resources are available, the partition can use
them if necessary.

Default: false
minimum-ifl- (w)(pc) Integer Represents the minimum amount of IFL processor
processing-weight resources allocated to the partition.

Valid range: 1-999

Default: 1
minimum-cp- (w)(pc) Integer Represents the minimum amount of general purpose
processing-weight processor resources allocated to the partition.

Valid range: 1-999

Default: 1
initial-ifl-processing- (w)(pc) Integer Defines the initial processing weight of IFL processors.
weight
Valid range: 1-999

Default: 100
initial-cp-processing- (w)(pc) Integer Defines the initial processing weight of CP processors.
weight
Valid range: 1-999

Default: 100
current-ifl-processing- (pc) Integer Defines the current IFL processing weight.
weight
current-cp-processing- (pc) Integer Defines the current CP processing weight.
weight
maximum-ifl- (w)(pc) Integer Represents the maximum amount of IFL processor
processing-weight resources allocated to the partition.

Valid range: 1-999

Default: 999
maximum-cp- (w)(pc) Integer Represents the maximum amount of shared general
processing-weight processor resources allocated to the partition.

Valid range: 1-999

Default: 999

Chapter 10. Dynamic Partition Manager (DPM) 151

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
processor- (w)(pc) Boolean Indicates whether the processor management is enabled.
management-enabled
Default: false
initial-memory (w)(pc) Integer The initial amount of memory to assign to the partition
when it is started, specified in MB. This value must be at
least 4096 when the partition's type is "ssc", and it must
be less than or equal to the value of maximum-memory.

Default: 1024
Note: If the value input by the user does not fall on an
increment boundary, it is rounded off to the closest
increment boundary.
reserved-memory (pc) Integer The amount of reserved memory in MB, which equals
maximum-memory minus initial-memory.
maximum-memory (w)(pc) Integer The maximum size, specified in MB, to which the
partition's memory allocation can be increased while the
partition is running. This value must be greater than or
equal to the value of initial-memory, and it must be no
larger than the amount of entitled memory on the system.

Default: 1024

Constraint: This property can only be updated when the

partition's status is "stopped".
Note: If the value input by the user does not fall on an
increment boundary, it is rounded off to the closest
increment boundary.
auto-start (pc) Boolean Indicates whether the partition is enabled for auto
activation.

If true, this partition is automatically started when the

CPC is activated.

Default: false

152 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
boot-device (w)(pc) String Enum The type of device from which the partition is booted
when it is started. Types:
v "storage-adapter" - Boot from the HBA specified in
"boot-storage-device".
| v "storage-volume" - Boot from the storage volume
| specified in "boot-storage-volume".
v "network-adapter" - Boot from the NIC specified in
"boot-network-device".
v "ftp" - Boot from the host specified in "boot-ftp-host".
v "removable-media" - Boot from HMC removable media
specified in "boot-removable-media".
v "iso-image" - Boot from the ISO image previously
mounted and associated with this partition.
v "none" - Implies that the partition is not currently
bootable.

Default: "none"
| Note: Because a newly created partition does not yet
| have any HBAs, NICs, mounted ISO images, nor does it
| have a storage-group attached, , boot device options
| "network-adapter", "storage-adapter", "iso-image" and
| "storage-volume" are not valid values for the boot-device
| field as specified in the request body for the Create
| Partition operation.

If the partition type is "ssc", only "none" can be set as the

boot-device when creating or updating a partition.
boot-network-device (w)(pc) String/ URI Specifies the network device that shall be used for the
network (PXE) boot.

The value must point to a valid NIC URI on the same

partition when boot-device mode is "network-adapter".

The value can be set to either null or a valid URI when

boot-device contains a value not relevant to this field.

Default: null
boot-ftp-host (w)(pc) String, String/IP Host name or the IP address of the FTP server that shall
V4 Address, be used for the FTP boot.
String/IP V6
Address The value must point to a valid host name or the IP
address when boot-device mode is "ftp".

The value can be set to either null or a valid host name

or IP address when boot-device contains a value not
relevant to this field.

Required if boot-device is "ftp".

Default: null

Chapter 10. Dynamic Partition Manager (DPM) 153

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
boot-ftp-username (w)(pc) String The user name for the account on the FTP server from
which the boot image shall be retrieved.

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "ftp".

Default: null
boot-ftp-password (wo)(pc) String The password for the account on the FTP server from
which the boot image shall be retrieved.

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "ftp".

boot-ftp-insfile (w)(pc) String The path to the INS-file on the FTP server.

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "ftp".

Default: null
boot-removable- (w)(pc) String Specifies the boot image or the CD/DVD or the USB
media media containing a bootable image. This must point to a
fully-qualified path on the HMC.

The value must point to a valid path name when

boot-device mode is "removable-media".

The value can be set to either null or a valid path name

when boot-device contains a value not relevant to this
field.

Required if boot-device is "removable-media".

Default: null
boot-removable- (w)(pc) String Enum Specifies the type of the removable media. Valid values
media-type are "cdrom" and "usb".

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "removable-media".

Default: null
boot-timeout (w)(pc) Integer (60-600) The time, in seconds, that is waited before an ongoing
boot is aborted. This is applicable for all modes of
boot-device.

Default: 60

154 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
| boot-storage-device (w)(pc) String/ URI Specifies the HBA that shall be used for the partition to
| boot.

The value has to point to a valid HBA URI on the

partition when boot-device mode is "storage-adapter".

The value can be set to either null or a valid HBA URI

when boot-device contains a value not relevant to this
field.

Default: null
| boot-storage-volume (w)(pc) String/ URI Specifies the volume that shall be used for the partition to
| boot.

| The value has to point to a valid URI of a storage volume

| of type "boot" contained in a storage group attached to
| the partition when boot-device is "storage-volume".

| The value can be set to either null or a valid boot volume

| URI when boot-device contains a value not relevant to
| this field.

| Default: null
boot-logical-unit- (w)(pc) String (1-16) The hexadecimal logical unit number (LUN) representing
number the boot device.

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "storage-adapter".

Default: an empty string

boot-world-wide-port- (w)(pc) String (16) The world wide port name (WWPN) of the storage
name controller containing the target SCSI device to be used for
boot, in hexadecimal.

The value can be set to either null or a valid value when

boot-device contains a value not relevant to this field.

Required if boot-device is "storage-adapter".

Default: an empty string

Chapter 10. Dynamic Partition Manager (DPM) 155

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
boot- (w)(pc) Integer Selects the boot configuration to use from among multiple
configuration-selector such boot configurations that have been defined by the
operating system to be loaded. Whether and how this
parameter is used to determine boot parameters depends
on the operating system and its boot process. For Linux
on z Systems®, for example, this parameter selects which
of the operating system's pre-configured boot
configurations is to be used, with the selected boot
configuration in turn specifying parameters such as the
kernel to be loaded, the kernel parameters to be used, or
which disk is used as part of the boot process.

Valid range: 0-30

Default: 0, which indicates that the operating system's

| default boot configuration should be used.
| Note: Not applicable if "boot-storage-volume" points to a
| FICON storage volume.
boot-record-lba (w)(pc) String (1-16) Specifies the logical block number, in hexadecimal, of the
anchor point for locating the operating system on the
SCSI disk from which the operating system is loaded. The
way in which this parameter is used to locate the
operating system depends on the operating system and
its boot process. For Linux on z Systems, for example,
this parameter specifies the block number of the master
boot record, which is usually the first block (block
number 0) on the boot device.

| Default: 0, identifying the first block on the device.

| Note: Not applicable if "boot-storage-volume" points to a
| FICON storage volume.
| boot-load-parameters (w)(pc) String (0-8) Specifies parameters that are passed unmodified to the
| operating system boot process. The way in which these
| parameters are used depends on the operating system,
| but in general, these parameters are intended to be used
| to select an entry in the boot menu or the boot loader.

| Valid characters are 0-9, A-Z, @, $, #, blank ( ), and period

| (.).

| Default: an empty string

boot-os-specific- (w)(pc) String (0-256) Specifies parameters that are passed unmodified to the
parameters loaded operating system as part of the boot process. The
way in which these parameters are used depends on the
operating system, but in general, these parameters are
intended to specify boot-time configuration settings. For
Linux on z Systems, for example, this property can be
used to specify kernel parameters.

Default: an empty string

| Note: Not applicable if "boot-storage-volume" points to a
| FICON storage volume.

156 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
boot-iso-image-name (pc) String Name of the ISO image. This property is changed by the
Mount ISO Image and Unmount ISO Image operations.

This name must not be an empty string, and it must not

contain any of the following characters: \,",<,>,|,:,&,$,*,/

Default: null
boot-iso-ins-file (w)(pc) String INS file location within the ISO image. This property is
changed by the Mount ISO Image and Unmount ISO
Image operations.

Default: null
access-global- (w)(pc) Boolean Indicates if global performance data authorization control
performance-data is requested.

Default: false
permit-cross- (w)(pc) Boolean Indicates if cross partition commands authorization
partition-commands control is requested.

Default: false
access-basic-counter- (w)(pc) Boolean Indicates if basic counter set authorization control is
set requested.

Default: false
access-problem-state- (w)(pc) Boolean Indicates if problem state counter set authorization
counter-set control is requested.

Default: false
access-crypto-activity- (w)(pc) Boolean Indicates is crypto activity counter set authorization
counter-set control is requested.

Default: false
access-extended- (w)(pc) Boolean Indicates if extended counter set authorization control is
counter-set requested.

Default: false
access-coprocessor- (w)(pc) Boolean Indicates if coprocessor group set authorization control is
group-set requested.

Default: false
access-basic-sampling (w)(pc) Boolean Indicates if basic CPU sampling authorization control is
requested.

Default: false
access-diagnostic- (w)(pc) Boolean Indicates if diagnostic sampling authorization control is
sampling requested.

May only be true if access-basic-sampling is true.

Default: false
permit-des-key- (w)(pc) Boolean Enables/disables the importing of DES keys for the
import-functions associated partition.

Default: true

Chapter 10. Dynamic Partition Manager (DPM) 157

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
permit-aes-key- (w)(pc) Boolean Enables/disables the importing of AES keys for the
import-functions associated partition.

Default: true
threads-per-processor (pc) Integer The number of threads the operating system running in
this partition can use, for each processor allocated. If the
partition has never been activated, a value of 0 is
returned. After the initial activation of the partition, this
value is controlled by the SMT (Simultaneous
Multi-Threading) setting in the OS.
virtual-function-uris (pc) Array of String/ Array of URIs referring to virtual functions associated
URI with the partition.

If the partition has no virtual functions, the array is

empty.

Default: an empty array

nic-uris (pc) Array of String/ Array of URIs referring to defined NICs (network
URI adapters) attached to the partition. If the partition has no
NICs, the array is empty.

Default: an empty array

hba-uris (pc) Array of String/ Array of URIs referring to defined HBAs attached to the
URI partition.

If the partition has no HBAs, the array is empty.

Default: an empty array

crypto-configuration (pc) crypto- Single instance of a crypto-configuration nested object.
configuration See “crypto-configuration object properties” on page 159.
object
The Increase Crypto Adapter Configuration operation
can be used to set the crypto configuration for the
partition.

Default: null
1
ssc-host-name (w)(pc) String/ Hostname The Secure Service Container host name. This string
meets the requirements of the String/Hostname data type
with the following exceptions:
v length is 1-64 characters
v valid characters are a-z, A-Z, 0-9, period(.), hyphen(-),
and underscore(_)
ssc-boot-selection1 (w)(pc) String Enum Indicates whether to run the Secure Service Container
appliance installer or the Secure Service Container
appliance itself. One of:
v "installer" - Boot the Secure Service Container
appliance installer to install the Secure Service
Container appliance and then start it.
v "appliance" - Start the most recently installed Secure
Service Container appliance and resume its execution
from where it was when the partition was stopped.

On an Update request, this property can be set from

"appliance" to "intaller" only.

Default: "installer"

158 HMC Web Services API

 Level 04a

Table 75. Partition object: class specific properties (continued)

Name Qualifier Type Description
1
ssc-ipv4-gateway (w)(pc) String/ IPv4 The default IPv4 Gateway to be used when there is at
Address least one NIC configured in static IPv4 mode.

Default: null
ssc-ipv6-gateway (w)(pc) String/ IPv6 The default IPv6 Gateway to be used when there is at
Address least one NIC configured in static IPv6 mode.

Default: null
1
ssc-dns-servers (w)(pc) Array of String/ The DNS IP address information. A minimum of 0 entries
IPv4 or IPv6 and a maximum of 2 entries are permitted. On an Update
Address request, this property fully replaces the existing set.

Default: An empty array

1
ssc-master-userid (w)(pc) String (1-32) The Secure Service Container master user ID. Valid
characters are: a-z, A-Z, 0-9, period(.), minus(-), and
underscore(_).

Default: null
1
ssc-master-pw (wo)(pc) String (8-256) The Secure Service Container master user password. Valid
characters are: a-z, A-Z, 0-9, and !@#$%^&*()_+{}|<>?-=.

Default: null
| available-features-list — Array of The list of optional features or behavior supported by this
| partition-feature- Partition. If the Partition has no optional features, then an
| info objects empty array is provided.
1
On a Get request, this property is returned only when type is "ssc". On an Update request, this property can be
updated only when type is "ssc".

| Table 76. partition-feature-info object properties

| Name Type Description
| name String Enum The name of the feature. One of:
| v "dpm-storage-management" - Indicates that the Partition
| supports Storage Groups and FICON storage resources. FCP
| and FICON storage resources are defined in Storage Groups,
| which are then attached to this Partition. If the Partition does
| not have this feature, FCP storage resources are represented
| by HBAs, which must be directly attached to this Partition.
| This feature is inherited from the "dpm-storage-
| management" feature on the hosting CPC object, and thus, is
| enabled only when the hosting CPC object has this feature
| enabled and is disabled otherwise.

| See Chapter 6, “Firmware features,” on page 63 for a list of

| operations that are affected for each of these features.
| description String A brief description of the feature.
| state Boolean Indicates if the feature is currently enabled (true) or disabled
| (false) for this Partition.
|

crypto-configuration object properties: The crypto configuration of a partition represents the elements
that are required to enable the partition to make use of crypto adapters. The configuration is a nested
structure, containing two pieces of information:
v A set of crypto adapters that will be used by this partition, and

Chapter 10. Dynamic Partition Manager (DPM) 159

 Level 04a

v A set of Crypto Domain Configuration objects. (See Table 78.)

A crypto configuration that contains no crypto adapters and no crypto domain configurations is valid
and is known as an empty crypto configuration. A non-empty configuration must contain at least 1 crypto
adapter and at least 1 crypto domain configuration with an access-mode of "control-usage".
Table 77. crypto-configuration nested object properties
Name Type Description
crypto-adapter-uris Array of Array of URIs listing all crypto adapters that this partition can use.
String/ URI
crypto-domain- Array of Array listing all crypto-domain-configuration objects for this partition. See
configurations crypto- Table 78.
domain-
configuration
objects

Table 78. crypto-domain-configuration nested object properties

Name Type Description
domain-index Integer Index value that identifies the domain to which this configuration applies.

Minimum index is 0, maximum index depends on the CPC model.

access-mode String Enum Specifies the way in which the partition can use this domain. Valid values
are:
v "control" - The partition can load cryptographic keys into the domain, but
it may not use the domain to perform cryptographic operations.
v "control-usage" - The partition can load cryptographic keys into the
domain, and it can use the domain to perform cryptographic operations.

Crypto configuration conflicts

A crypto configuration conflict occurs when the crypto configuration of two (or more) partitions:
1. Have one (or more) adapter(s) in common, and
2. Specified "control-usage" for one (or more) identical domain index(es).

No more than one of the partitions involved in a given crypto configuration conflict may be active or
have reserved resources at any one point in time.

According to this definition, the crypto configuration of two partitions can have multiple conflicts
(regarding different adapters and/or different domains).

It is also possible for a partition to be involved in conflicts with multiple other partitions. For example,
Partition A has 3 crypto adapters in its configuration. Partition B has 2 of those and Partition C has the
other one. Assuming they all have a control-usage domain in common, Partition A is now involved in a
conflict with Partition B and a separate conflict with Partition C.

Such conflicts are only allowed for partitions that are in "stopped" state, and without reserved resources.
That means the system will prevent the creation of conflicting crypto configuration for the set of active
partitions, and the set of "stopped" partitions that have reserve-resources enabled.

160 HMC Web Services API

 Level 04a

Data model - Virtual Function element object

The following table contains the Virtual Function element object properties.
Table 79. Partition object - Virtual Function element properties
Name Qualifier Type Description of specialization
element-id — String (36) The unique identifier for the virtual function instance.
element-uri — String/ The canonical URI path for the virtual function is of the form
URI /api/partitions/{partition-id}/virtual-functions/{virtual-
function-id}, where {partition-id} is the object-id of the partition,
and the {virtual-function-id} is the element-id of the virtual function.
parent — String/ The URI path of the partition that hosts this virtual function.
URI
class — String (16) Always "virtual-function".
name (w)(pc) String Name of the virtual function. The name must be unique among all
(1-64) virtual functions of the partition. The length and character
requirements on this property are the same as those described in
the “Base managed object properties schema” on page 60.
description (w)(pc) String Description of the virtual function.
(0-1024)
Default: an empty string.
device-number (w)(pc) String (4) Device number of the virtual function.

The string is in the form of a 4-digit hexadecimal number. The

allowed value range is from 0001-FFFF.

Default: auto-generated.

Constraint: This number must be unique across the device numbers

of all other Virtual Function elements and all NIC elements of type
"roce" of the partition.
adapter-uri (w)(pc) String/ The canonical URI path for the associated Accelerator adapter.
URI
fid — Integer Functional ID of the associated accelerator adapter identified in
adapter-uri, or null if the partition is not active.

Data model - NIC element object

The following table contains the NIC element object properties.
Table 80. Partition object - NIC element object properties
Name Qualifier Type Description of specialization
element-id — String (36) The unique identifier for the NIC within the scope of the partition.
element-uri — String/ The canonical URI path for the NIC is of the form
URI /api/partitions/{partition-id}/nics/{nic-id}, where
{partition-id} is the object-id of the partition, and the {nic-id} is the
element-id of the NIC.
parent — String/ The URI path of the partition that hosts this NIC.
URI
class — String (3) Always "nic".
name (w)(pc) String Name of the NIC. The name must be unique among all NICs of the
(1-64) partition. The length and character requirements on this property
are the same as those described in the “Base managed object
properties schema” on page 60.

Chapter 10. Dynamic Partition Manager (DPM) 161

 Level 04a

Table 80. Partition object - NIC element object properties (continued)

Name Qualifier Type Description of specialization
description (w)(pc) String Description of the NIC.
(0-1024)
Default: an empty string.
device-number (w)(pc) String (4) Device number of the NIC.

The string is in the form of a 4-digit hexadecimal number. The

allowed value range is from 0001-FFFF.

Default: auto-generated.

Constraint: If type is "roce", this number must be unique across the

device numbers of all other NIC elements of type "roce" and
among all Virtual Function elements of the partition. If type is
"iqd" or "osd", this number must be unique across the device
numbers of all other NIC elements of type "iqd" or "osd" and all
HBA elements of the partition.
network-adapter- (w)(pc) String/ The canonical URI path for the associated Network Port element
port-uri URI object.

Only present when type is "roce".

virtual-switch-uri (w)(pc) String/ The canonical URI path for the associated Virtual Switch object.
URI
Only present when type is "osd" or "iqd".
type — String The type of the NIC. The value of this property is derived
Enum implicitly from the backing adapter associated with this NIC on the
Create NIC operation. Valid values are:
v "roce" - RDMA over Converged Ethernet.
v "iqd" - Internal Queued Direct.
v "osd" - OSA Direct Express
ssc-management-nic (w)(pc) Boolean Indicates that this NIC should be used as a management NIC for
Secure Service Container to access the web interface.

Can only be set to true if the partition's type is "ssc".

If the partition's type is "ssc", there must be at least one

management NIC defined before the partition can be started.

If true, other parameters are required (at least ssc-ip-address-type)

for this NIC.

If true, only OSA or HiperSockets adapters can be selected as

backing adapters.

If the associated SE is version 2.13.1, the only valid port for an OSA
backing adapter is port 0.
ssc-ip-address-type1 (w)(pc) String Secure Service Container IP address type. Valid types are:
Enum v "ipv4" - Network is configured in static IPv4 mode
v "ipv6" - Network is configured in static IPv6 mode
v "linklocal" - Network is configured in Link Local mode
v "dhcp" - Network is configured in DHCP mode.

162 HMC Web Services API

 Level 04a

Table 80. Partition object - NIC element object properties (continued)

Name Qualifier Type Description of specialization
1
ssc-ip-address (w)(pc) String/ The IP address of the Secure Service Container management web
IPv4 interface.
Address or
String/
IPv6
Address
ssc-mask-prefix1 (w)(pc) String Network mask of the Secure Service Container management NIC.
Either the mask is provided in bit notation, e.g. "/24" (both for IPv4
and IPv6), or in mask notation, e.g. "255.255.255.0" (IPv4 only).
vlan-id (w)(pc) Integer The VLAN ID associated with this NIC.
(1-4094)
When the partition's type is "ssc", this property is allowed only if
the value of ssc-management-nic is "true". It can be null.

When the partition's type is not "ssc", this property is not allowed
when the type of the NIC is "roce".
mac-address (w)(pc) String (17) The MAC address associated with this NIC. It must be unique
among all the NICs created in the CPC.

The MAC address is represented as six groups of two lower-case

hexadecimal digits separated by colons (:). Only locally
administered unicast MAC addresses are valid, e.g.
"02:ff:12:34:56:78".

This value can not be set when the type of the NIC is "roce".

Default: Auto-generated
vlan-type (w)(pc) String The type of VLAN tagging to use for the VLAN associated with
Enum this NIC, or null, if the NIC is not associated with a VLAN. Valid
value:
v "enforced" - the network adapter only allows untagged packets
or packets tagged for the VLAN identified by vlan-id through to
the operating system running in the partition. The network
device in the operating system should also be configured with
the same vlan-id.

This value can not be set when the partition's type is "ssc" or when
the type of the NIC is "roce".
1
Only applicable if ssc-management-nic is true.

Data model - HBA element object

An HBA represents a single Host Bus Adapter (HBA) available to a partition in a CPC. An HBA is an
access point between a CPC and a Storage Area Network (SAN).

The following table contains the HBA element object properties.

Table 81. Partition object - HBA element object properties
Name Qualifier Type Description of specialization
element-uri — String/ The canonical URI path of an HBA element is of the form
URI /api/partitions/{partition-id}/hbas/{hba-id} where
{partition-id} represents the object-id of the Partition object and
{hba-id} represents the element-id of the HBA.
element-id — String (36) The unique identifier for an HBA element. The string form of a
UUID.

Chapter 10. Dynamic Partition Manager (DPM) 163

 Level 04a

Table 81. Partition object - HBA element object properties (continued)

Name Qualifier Type Description of specialization
parent — String/ The canonical URI path of the Partition object.
URI
class — String The class of an HBA element is "hba".
name (w)(pc) String The display name of an HBA element. This name must be unique
(1-64) among all of the partition's HBA elements, and it must conform to
the length and character requirements of the name property
described in the “Base managed object properties schema” on page
60.
description (w)(pc) String The description of the HBA element.
(0-1024)
Default: an empty string.
wwpn — String (16) The world wide port name of the HBA element. The string form of
wwpn is of 16 hexadecimal characters.
device-number (w)(pc) String (4) Device number of the HBA.

The string is in the form of a 4-digit hexadecimal number. The

allowed value range is from 0001-FFFF.

Default: auto-generated.

Constraint: This number must be unique across the device numbers

of all other HBA elements and all NIC elements of type "iqd" or
"osd" of the partition.
adapter-port-uri (pc) String/ The canonical URI path of the Storage Port element object to which
URI this HBA is connected.

List Partitions of a CPC

The List Partitions of a CPC operation lists the partitions of a CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/partitions

In this request, the URI variable {cpc-id} is the object ID of the target CPC.

Query parameters:

Name Type Rqd/Opt Description

name String Optional A regular expression used to limit returned objects to those that have
a matching name property.
status String Optional Filter string to limit returned objects to those that have a matching
Enum status property. Value must be a valid partition status property
value.
type String Optional Filter string to limit returned objects to those that have a matching
Enum type property. Value must be a valid partition type property value.

164 HMC Web Services API

 Level 04a

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description

partitions Array of Array of nested partition-info objects, described in the next table.
partition-
info
objects

Each nested partition-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Partition object.
URI
name String The name property of the Partition object.
status String The status property of the Partition object.
Enum
type String The type property of the Partition object.
Enum

Description
This operation lists the partition objects that belong to a CPC. The object URI, display name, status, and
type are provided for each.

If the name query parameter is specified, the returned list is limited to those partition objects that have a
name property matching the specified filter pattern. If the status query parameter is specified, the
returned list is limited to those partition objects that have a status property matching the specified filter
value. If the type query parameter is specified, the returned list is limited to those partition objects that
have a type property matching the specified filter value. If no query parameters are provided, no filtering
is done.

An object is only included in the list if the API user has object-access permission for that object

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents.”

If the CPC is not in DPM mode, or there are no partitions defined to the CPC, or no partitions are to be
included in the response due to filtering or access permissions, an empty list is provided and the
operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}.
v Object-access permission to any Partition object to be included in the result.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents.”

Chapter 10. Dynamic Partition Manager (DPM) 165

 Level 04a

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The request URI does not designate an existing resource of the expected
type, or designates a resource for which the API user does not have
object-access permission.
409 (Conflict) 329 The operation cannot be performed because the CPC designated by the
request URI is an unmanaged CPC, which is not supported by this
operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

GET /api/cpcs/93634ff4-0599-3f7d-b937-7673de7dfd0c/partitions?name=t.* HTTP/1.1

x-api-session: 2izurpik57ciomzst8z0q1vsqg2kuvfe9qxdja6irmbovo8z1c

Figure 23. List Partitions of a CPC: Request

166 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Feb 2017 09:08:33 GMT
content-type: application/json;charset=UTF-8
content-length: 504
{
"partitions":[
{
"name":"testpweights",
"object-uri":"/api/partitions/2fa1f646-e9d9-11e6-a392-42f2e9cfe851",
"status":"stopped",
"type":"ssc"
},
{
"name":"testVnic",
"object-uri":"/api/partitions/bc09b56e-e88b-11e6-8715-42f2e9cfe851",
"status":"active",
"type":"linux"
},
{
"name":"testCrypto",
"object-uri":"/api/partitions/798167ba-ec4a-11e6-a040-42f2e9cfe851",
"status":"stopped",
"type":"linux"
},
{
"name":"test_ah",
"object-uri":"/api/partitions/fd93be7e-e928-11e6-bcc9-42f2e9cfe851",
"status":"stopped",
"type":"ssc"
}
]
}

Figure 24. List Partitions of a CPC: Response

List Permitted Partitions

The List Permitted Partitions operation lists partitions to which the API user has object-access
permission.

HTTP method and URI

GET /api/console/operation/list-permitted-partitions

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) to limit returned objects to those
that have a matching name property.
type String Optional Filter string to limit returned objects to those that have a matching
Enum type property. Value must be a valid partition type property value.
status String Optional Filter string to limit returned objects to those that have a matching
Enum status property. Value must be a valid partition status property
value.
has-unacceptable- Boolean Optional Filter string to limit returned objects to those that have a matching
status has-unacceptable-status property. Valid values are true and false.

Chapter 10. Dynamic Partition Manager (DPM) 167

 Level 04a

Name Type Rqd/Opt Description

cpc-name String Optional Filter pattern (regular expression) to limit returned objects to those
whose parent CPC has a matching name property.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description

partitions Array of Array of nested partition-info objects as described in the next table.
partition-
info
objects

Each nested partition-info object contains the following fields:

Field name Type Description

name String The name property of the Partition object.
object-uri String/ The object-uri property of the Partition object.
URI
type String The type property of the Partition object.
Enum
status String The status property of the Partition object.
Enum
has-unacceptable-status Boolean The has-unacceptable-status property of the Partition object.
cpc-name String The name property of the partition's parent CPC object.
cpc-object-uri String/ The object-uri property of the partition's parent CPC object.
URI

Description
This operation lists the Partition objects to which the API user has object-access permission. Some basic
properties are provided for each partition that is included in the response.

If the name query parameter is specified, the returned list is limited to those partitions that have a name
property matching the specified filter pattern. If the name parameter is omitted, no such filtering is
performed.

If the type query parameter is specified, the parameter is validated to ensure it is a valid partition type
property value. If the value is not valid, HTTP status code 400 (Bad Request) is returned. If the value is
valid, the returned list is limited to those partitions that have a type property matching the specified
value. If the type parameter is omitted, no such filtering is performed.

If the status query parameter is specified, the parameter is validated to ensure it is a valid partition
status property value. If the value is not valid, HTTP status code 400 (Bad Request) is returned. If the
value is valid, the returned list is limited to those partitions that have a status property matching the
specified value. If the status parameter is omitted, no such filtering is performed.

If the has-unacceptable-status query parameter is specified, the returned list is limited to those partitions
that have a has-unacceptable-status property matching the specified value. If the has-unacceptable-status
parameter is omitted, no such filtering is performed.

168 HMC Web Services API

 Level 04a

If the cpc-name query parameter is specified, the returned list is limited to those partitions whose parent
CPC's name property matches the specified filter pattern. If the cpc-name parameter is omitted, no such
filtering is performed.

A partition is included in the list only if the API user has object-access permission to that object. If there
is a partition to which the API user does not have permission, that object is omitted from the list, but no
error status code results.

If there are no partitions known to the HMC or if no partitions are to be included in the response due to
filtering or access permissions, an empty list is provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Partition objects included in the response body.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in
“Response body contents” on page 168.

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

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

GET /api/console/operations/list-permitted-partitions HTTP/1.1

x-api-session: 1hxko1kyziy64pcd9a9ot59ceb9jnh7vg55ylro930kubzgva5

Figure 25. List Permitted Partitions: Request

Chapter 10. Dynamic Partition Manager (DPM) 169

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 28 Aug 2017 18:37:52 GMT
content-type: application/json;charset=UTF-8
content-length: 272
{
"partitions":[
{
"cpc-name":"SEDPM005",
"cpc-object-uri":"/api/cpcs/e4e18781-8063-3f2c-8222-044eb58988d9",
"has-unacceptable-status":true,
"name":"part1",
"object-uri":"/api/partitions/592125be-76dd-11e7-94f9-02c2000226b7",
"status":"communications-not-active",
"type":"linux"
}
]
}

Figure 26. List Permitted Partitions: Response

Usage note
The response body of this operation is similar to that of the Get Inventory operation, but it returns only
a subset of partition properties. The response also includes some properties of the parent CPC, regardless
of whether the API user has object-access permission to that CPC.

Create Partition
The Create Partition operation creates a partition with the given properties on the identified CPC.

HTTP method and URI

POST /api/cpcs/{cpc-id}/partitions

In this request, the URI variable {cpc-id} is the object ID of the CPC.

Request body contents

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

Field name Type Rqd/Opt Description

type String Optional The value to be set as the partition's type
Enum property.
name String (1-64) Required The value to be set as the partition's name
property.
description String Optional The value to be set as the partition's
(0-1024) description property.
short-name String (8) Optional The value to be set as the partition's
short-name property.
partition-id String (2) Required if The value to be set as the partition's
autogenerate- partition-id property.
partition-id is false
autogenerate-partition-id Boolean Optional The value to be set as the partition's
autogenerate-partition-id property.

170 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

ifl-processors Integer Required if The value to be set as the partition's
cp-processors is not ifl-processors property.
provided
cp-processors Integer Required if The value to be set as the partition's
ifl-processors is not cp-processors property.
provided
processor-mode String Optional The value to be set as the partition's
Enum processor-mode property.
initial-memory Integer Required The value to be set as the partition's
initial-memory property.
maximum-memory Integer Required The value to be set as the partition's
maximum-memory property.
reserve-resources Boolean Optional The value to be set as the partition's
reserve-resources property.
boot-device String Optional The value to be set as the partition's
Enum boot-device property.
boot-timeout Integer Optional The value to be set as the partition's
(60-600) boot-timeout property.
boot-ftp-host String Required if The value to be set as the partition's
boot-device is "ftp" boot-ftp-host property.
boot-ftp-username String Required if The value to be set as the partition's
boot-device is "ftp" boot-ftp-username property.
boot-ftp-password String Required if The value to be set as the partition's
boot-device is "ftp" boot-ftp-password property.
boot-ftp-insfile String Required if The value to be set as the partition's
boot-device is "ftp" boot-ftp-insfile property.
boot-removable-media String Required if The value to be set as the partition's
boot-device is boot-removable-media property.
"removable-"
media"
boot-removable-media-type String Required if The value to be set as the partition's
Enum boot-device is boot-removable-media-type property.
"removable-"
media"
access-global-performance- Boolean Optional The value to be set as the partition's
data access-global-performance-data property.
permit-cross-partition- Boolean Optional The value to be set as the partition's
commands permit-cross-partition-commands property.
access-basic-counter-set Boolean Optional The value to be set as the partition's
access-basic-counter-set property.
access-problem-state- Boolean Optional The value to be set as the partition's
counter-set access-problem-state-counter-set property.
access-crypto-activity- Boolean Optional The value to be set as the partition's
counter-set access-crypto-activity-counter-set property.
access-extended-counter-set Boolean Optional The value to be set as the partition's
access-extended-counter-set property.
access-coprocessor-group- Boolean Optional The value to be set as the partition's
set access-coprocessor-group-set property.

Chapter 10. Dynamic Partition Manager (DPM) 171

 Level 04a

Field name Type Rqd/Opt Description

access-basic-sampling Boolean Optional The value to be set as the partition's
access-basic-sampling property.
access-diagnostic-sampling Boolean Optional The value to be set as the partition's
access-diagnostic-sampling property.
permit-des-key-import- Boolean Optional The value to be set as the partition's
functions permit-des-key-import-functions property.
permit-aes-key-import- Boolean Optional The value to be set as the partition's
functions permit-aes-key-import-functions property.
ssc-host-name String/ Required, if type is The value to be set as the partition's
Hostname "ssc" ssc-host-name property.
ssc-ipv4-gateway String/ IPv4 Optional The value to be set as the partition's
Address ssc-ipv4-gateway property.
ssc-ipv6-gateway String/ IPv6 Optional The value to be set as the partition's
Address ssc-ipv6-gateway property.
ssc-dns-servers Array of Optional The value to be set as the partition's
String/ IPv4 ssc-dns-servers property.
or IPv6
Address
ssc-master-userid String Required, if type is The value to be set as the partition's
"ssc" ssc-master-userid property.
ssc-master-pw String Required, if type is The value to be set as the partition's
"ssc" ssc-master-pw property.
initial-ifl-processing- Integer Optional The value to be set as the partition's
weight (1-999) initial-ifl-processing-weight property.
initial-cp-processing- Integer Optional The value to be set as the partition's
weight (1-999) initial-cp-processing-weight property.
acceptable-status Array of Optional The value to be set as the partition's
String acceptable-status property.
Enum
cp-absolute-processor- Boolean Optional The value to be set as the partition's
capping cp-absolute-processor-capping property.
cp-absolute-processor- Float Optional The value to be set as the partition's
capping-value cp-absolute-processor-capping-value property.
cp-processing-weight-capped Boolean Optional The value to be set as the partition's
cp-processing-weight-capped property.
ifl-absolute-processor- Boolean Optional The value to be set as the partition's
capping ifl-absolute-processor-capping property.
ifl-absolute-processor- Float Optional The value to be set as the partition's
capping-value ifl-absolute-processor-capping-value property.
ifl-processing-weight- Boolean Optional The value to be set as the partition's
capped ifl-processing-weight-capped property.
maximum-cp-processing- Integer Optional The value to be set as the partition's
weight maximum-cp-processing-weight property.
maximum-ifl-processing- Integer Optional The value to be set as the partition's
weight maximum-ifl-processing-weight property.
minimum-cp-processing- Integer Optional The value to be set as the partition's
weight minimum-cp-processing-weight property.
minimum-ifl-processing- Integer Optional The value to be set as the partition's
weight minimum-ifl-processing-weight property.

172 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

processor-management- Boolean Optional The value to be set as the partition's
enabled processor-management-enabled property.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description

object-uri String/URI The object-uri property of the created partition.

Description
This operation creates a partition with the values specified on the identified CPC and then returns its
object-uri in the response body. The response also includes a Location header that provides this URI. An
Inventory Change notification is emitted asynchronously to this operation.

Any properties identified as required must be included in the request body. Any properties identified as
optional may be excluded from the request body; if an optional property is not found in the request body,
its value will be set to its default value.

If the request body contents are valid, the partition is created on the target CPC and its properties are
defined to their corresponding request body content's properties' values. If a property is omitted from the
request body, its default value is used when creating the partition.

If the API user does not have action/task permission to the New Partition task, a 403 (Forbidden) status
code is returned. A 404 (Not Found) status code is returned if the object-id {cpc-id} does not identify a
CPC object for which the API user has object-access permission.

If the request body contents fail to validate, a 400 (Bad Request) status code is returned. This may occur
because the document fails to define a required property. This may also occur if the document fails to
define a single valid partition, for instance defining a property with an invalid value (e.g. an
initial-memory value less than zero, or a name that is already in use). If the status of the CPC is not
valid (The valid states are "active", "service-required", "degraded", "exceptions"), 409 (Conflict) status
code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC identified by {cpc-id}.
v Action/task permission to the New Partition task.

HTTP status and reason codes

On success, HTTP status code 201 (Created) 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. The response body is a standard
error response body providing the reason code indicated and associated error message.

Chapter 10. Dynamic Partition Manager (DPM) 173

 Level 04a

Table 82. Create Partition: HTTP status and reason codes

HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
8 A partition with the name specified in the request body already exists.
15 The specified access-diagnostic-sampling value is not valid when
access-basic-sampling is false.
18 A property that is only valid for type "ssc" was provided, but the type is not
"ssc".

The partition type "ssc" only allows "none" for boot-device.

20 The type "ssc" is not supported by the targeted CPC.
117 boot-device cannot be set to "network-adapter", "storage-adapter",
"storage-volume", or "iso-image" at the time of partition creation.
118 There is an error in the fields related to the partition ID. One of:
v autogenerate-partition-id is false and the partition-id specified in the
request body is already in use.
v autogenerate-partition-id is false and partition-id is not included in the
request body.
v autogenerate-partition-id is true and partition-id is included in the
request body.
403 (Forbidden) 1 API user does not have action/task permission to the New Partition task.
404 (Not Found) 1 The CPC with object ID {cpc-id} does not exist, or the API user does not have
object-access permission to it.
409 (Conflict) 1 The operation cannot be performed because the CPC designated by the URI
does not have a valid status. The valid states are "active", "service-required",
"degraded", and "exceptions".
2 The operation cannot be performed because the CPC designated by the
request URI is currently busy performing some other operation.
5 The operation cannot be performed because the CPC designated by the
request URI is currently not enabled for DPM.
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
116 The reserve-resources value is true but resources are not available to be
reserved for this partition's use.
329 The operation cannot be performed because the CPC designated by the
request URI is an unmanaged CPC, which is not supported by this
operation.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

174 HMC Web Services API

 Level 04a

Example HTTP interaction

Create Partition: Request

POST /api/cpcs/d49a116c-d938-3b87-ad7c-444752db1216/partitions HTTP/1.1
x-api-session: v6n1aljy1tmlsjq7ki955u0s4t7qr8xabmiu0pbpbadgq7fe
content-type: application/json
content-length: 117
{
"name":"Partition",
"cp-processors":3,
"initial-memory":1024,
"maximum-memory":2048,
"processor-mode":"shared"
}

Figure 27. Create Partition: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/9cfdf912-89cf-11e5-8092-020000000056
cache-control: no-cache
date: Fri, 13 Nov 2015 06:26:42 GMT
content-type: application/json;charset=UTF-8
content-length: 69
{
"object-uri":"/api/partitions/9cfdf912-89cf-11e5-8092-020000000056"
}

Figure 28. Create Partition: Response

Delete Partition
The Delete Partition operation deletes the identified partition.

HTTP method and URI

DELETE /api/partitions/{partition-id}

In this request, the URI variable {partition-id} is the object ID of the Partition object.

Description
This operation deletes the designated partition, which includes the following actions:
v The partition's HBAs are disassociated from their backing physical adapters and deleted.
v The partition's NICs are disassociated from their backing virtual switches and deleted.
v The partition's virtual functions are disassociated from their backing physical adapters and deleted.
v The partition is disassociated from the crypto adapters and crypto domains for which it was
configured.
v The ISO image is deleted.
v An Inventory Change notification is emitted asynchronously to this operation.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a partition object
for which the API user has object-access permission. If the API user does not have action/task permission
to the Delete Partition operation, a 403 (Forbidden) status code is returned. A 409 (Conflict) status code is
returned if status of either the partition or the CPC is not valid to perform the operation. A 409 (Conflict)
status code is also returned if another operation targeting the partition is already underway.

Chapter 10. Dynamic Partition Manager (DPM) 175

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition.
v Action/task permission to the Delete Partition task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

The following HTTP status codes are returned for the indicated errors. The response body is a standard
error response body providing the reason code indicated and associated error message.
Table 83. Delete Partition: HTTP status and reason codes
HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden 1 API user does not have action permission to the Delete Partition task.
404 (Not Found) 1 The partition with the object ID {partition-id} does not exist, or the API user
does not have object-access permission to it.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "stopped").
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation. The valid states are "active", "service-required", "degraded", and
"exceptions".
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
110 The operation cannot be performed as the partition is a member of a
Capacity Group.
112 The operation cannot be performed as the partition is targeted in a
scheduled operation.
113 The operation cannot be performed as the partition is configured to be
automatically started when its hosting CPC starts.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

DELETE /api/partitions/9cfdf912-89cf-11e5-8092-020000000056 HTTP/1.1

x-api-session: 515ad9soju9cvqsyxkcq3d65c1v2bd6e8rhz4pu2psps2jae1f

Figure 29. Delete Partition: Request

176 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 13 Nov 2015 06:30:12 GMT

<No response body>

Figure 30. Delete Partition: Response

Usage note
This is a synchronous operation and as such does not complete until the partition has been deleted.
Depending on the I/O configuration associated with the partition, this operation may take a considerable
amount of time to complete. API clients that are concerned about that should use the Delete Partition
Asynchronously operation instead.

Delete Partition Asynchronously

The Delete Partition Asynchronously operation deletes the identified partition asynchronously.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/async-delete

In this request, the URI variable {partition-id} is the object ID of the Partition object.

Response body contents

Once the delete request 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.

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” on page
179. The job-results field contains null when the operation is successful. When it is not 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.

Description
This operation asynchronously deletes the designated partition. When the operation is initiated, a 202
(Accepted) status code is returned. The response body contains a URI that may be queried to retrieve the
status of the operation. See “Query Job Status” on page 80 for information on how to query job status.
When the operation has completed, an asynchronous result message is sent, with Job Status and Reason
Codes described in “Job status and reason codes” on page 179.

Chapter 10. Dynamic Partition Manager (DPM) 177

 Level 04a

The deletion includes the following actions:

v The partition's HBAs are disassociated from their backing physical adapters and deleted.
v The partition's NICs are disassociated from their backing virtual switches and deleted.
v The partition's virtual functions are disassociated from their backing physical adapters and deleted.
v The partition is disassociated from the crypto adapters and crypto domains for which it was
configured.
v The ISO image is deleted.
v An Inventory Change notification is emitted asynchronously to this operation.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a Partition object
for which the API user has object-access permission. If the API user does not have authority to perform
the Delete Partition operation, a 403 (Forbidden) status code is returned. A 409 (Conflict) status code is
returned if the status of either the partition or the CPC is not valid to perform the operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition.
v Action/task permission to the Delete Partition 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” on page 177.

The following HTTP status codes are returned for the indicated errors. The response body is a standard
error response body providing the reason code indicated and associated error message.
Table 84. Delete Partition Asynchronously: HTTP status and reason codes
HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden 1 API user does not have the required permission for this operation.
404 (Not Found) 1 The object-id in the URI {partition-id} does not designate an existing Partition
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "stopped" or
"reservation-error").
6 The state of the CPC hosting the partition is not valid to perform the
operation. It must be in one of the following states: "active",
"service-required", "degraded", and "exceptions".
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

178 HMC Web Services API

 Level 04a

Job status and reason codes

Table 85. Delete Partition Asynchronously: Job status and reason codes
HTTP error status Reason
code code Description
204 (No Content) N/A Delete completed successfully.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "stopped" or
"reservation-error").
2 The operation canot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation. It must be in one of the following states: "active",
"service-required", "degraded", and "exceptions".
110 The operation cannot be performed as the partition is a member of a
Capacity Group.
112 The operation cannot be performed as the partition is targeted in a
scheduled operation.
113 The operation cannot be performed as the partition is configured to be
automatically started when its hosting CPC starts.
500 (Server Error) 100 Partition delete failed.
101 Partition delete job timed out.

Example HTTP interaction

POST /api/partitions/279cee22-50d3-11e7-b285-fa163ef98b8b/operations/async-delete HTTP/1.1

x-api-session: 37o1ukpoqdqwa64iggv0gjtfx6q9xsdihiquuidnvdh5s8twc9
content-type: application/json

Figure 31. Delete Partition Asynchronously: Request

202 Accepted
server: Hardware management console API web server / 2.0
location: /api/jobs/3ae9a3c8-55b3-11e7-b883-fa163e6e13bb
cache-control: no-cache
date: Tue, 20 Jun 2017 12:23:13 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/3ae9a3c8-55b3-11e7-b883-fa163e6e13bb"
}

Figure 32. Delete Partition Asynchronously: Response

Get Partition Properties

The Get Partition Properties operation retrieves the properties of a single Partition object.

HTTP method and URI

GET /api/partitions/{partition-id}

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Chapter 10. Dynamic Partition Manager (DPM) 179

 Level 04a

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Partition object as defined in the “Data model” on page 146. Field names and data
types in the JSON object are the same as the property names and data types defined in the data model.

Description
The Get Partition Properties operation returns the current values of the properties for the Partition object
as defined in the “Data model” on page 146.

The URI path must designate an existing Partition object and the API user must have object-access
permission to it. If either of these conditions is not met, status code 404 (Not Found) is returned.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the
current properties as defined in the “Data model” on page 146. A 404 (Not Found) status code is returned
if the object-id {partition-id} does not identify a partition object for which the API user has object-access
permission.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Partition object designated by {partition-id}

HTTP status and reason codes

On success, HTTP status code 200 (OK) 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. The response body is a standard
error response body providing the reason code indicated and associated error message.

HTTP error status Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
404 (Not Found) 1 The object ID in the URI {partition-id} does not designate an existing Partition
object, or the API user does not have object-access permission to it.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Example HTTP interaction

GET /api/partitions/aa245764-b64f-11e6-9ee6-42f2e9cfe851 HTTP/1.1

x-api-session: 3ikod8v41qpbypte20906jzcavwrnkg51fs8jjjyeipexgvp50

Figure 33. Get Partition Properties: Request

180 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 03 Feb 2017 09:26:58 GMT
content-type: application/json;charset=UTF-8
content-length: 2509
{
"acceptable-status":[
"active"
],
"access-basic-counter-set":false,
"access-basic-sampling":false,
"access-coprocessor-group-set":false,
"access-crypto-activity-counter-set":false,
"access-diagnostic-sampling":false,
"access-extended-counter-set":false,
"access-global-performance-data":false,
"access-problem-state-counter-set":false,
"auto-start":false,
"autogenerate-partition-id":true,
"available-features-list":[
{
"description":"The DPM storage management approach in which FCP and FICON storage
resources are defined in Storage Groups, which are attached to Partitions.",
"name":"dpm-storage-management",
"state":true
}
],
"boot-configuration-selector":0,
"boot-device":"test-operating-system",
"boot-ftp-host":null,
"boot-ftp-insfile":null,
"boot-ftp-username":null,
"boot-iso-image-name":null,
"boot-iso-ins-file":null,
"boot-logical-unit-number":"",
"boot-network-device":null,
"boot-os-specific-parameters":"",
"boot-record-lba":"0",
"boot-removable-media":null,
"boot-removable-media-type":null,
"boot-storage-device":null,
"boot-timeout":60,
"boot-world-wide-port-name":"",
"class":"partition",
"cp-absolute-processor-capping":false,
"cp-absolute-processor-capping-value":1.0,
"cp-processing-weight-capped":false,
"cp-processors":1,
"crypto-configuration":null,
"current-cp-processing-weight":1,
"current-ifl-processing-weight":1,
"degraded-adapters":[
"/api/partitions/aa245764-b64f-11e6-9ee6-42f2e9cfe851/hbas/526e0708-bbc3-11e6-9043-
42f2e9cfe851"
],

Figure 34. Get Partition Properties: Response (Part 1)

Chapter 10. Dynamic Partition Manager (DPM) 181

 Level 04a

"description":"",
"has-unacceptable-status": true,
"hba-uris":[
"/api/partitions/aa245764-b64f-11e6-9ee6-42f2e9cfe851/hbas/526e0708-bbc3-11e6-9043-
42f2e9cfe851"
],
"ifl-absolute-processor-capping":false,
"ifl-absolute-processor-capping-value":1.0,
"ifl-processing-weight-capped":false,
"ifl-processors":0,
"initial-cp-processing-weight":100,
"initial-ifl-processing-weight":100,
"initial-memory":4096,
"is-locked":false,
"maximum-cp-processing-weight":999,
"maximum-ifl-processing-weight":999,
"maximum-memory":4096,
"minimum-cp-processing-weight":1,
"minimum-ifl-processing-weight":1,
"name":"sampleTest",
"nic-uris":[
"/api/partitions/aa245764-b64f-11e6-9ee6-42f2e9cfe851/nics/5217cc44-bbc3-11e6-9043-
42f2e9cfe851"
],
"object-id":"aa245764-b64f-11e6-9ee6-42f2e9cfe851",
"object-uri":"/api/partitions/aa245764-b64f-11e6-9ee6-42f2e9cfe851",
"os-name":"",
"os-type":"Linux",
"os-version":"3.10.0",
"parent":"/api/cpcs/93634ff4-0599-3f7d-b937-7673de7dfd0c",
"partition-id":"00",
"permit-aes-key-import-functions":true,
"permit-cross-partition-commands":false,
"permit-des-key-import-functions":true,
"processor-management-enabled":false,
"processor-mode":"shared",
"reserve-resources":false,
"reserved-memory":0,
"short-name":"SAMPLE",
"status":"degraded",
"threads-per-processor":1,
"type":"linux",
"virtual-function-uris":[]
}

Figure 35. Get Partition Properties: Response (Part 2)

Update Partition Properties

The Update Partition Properties operation updates one or more of the writable properties of the Partition
object designated by {partition-id}.

HTTP method and URI

POST /api/partitions/{partition-id}

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

182 HMC Web Services API

 Level 04a

Request body contents

The request body is expected to contain one or more field names representing writable partition
properties, along with the new values for those fields. The request body can and should omit fields for
properties whose values are not to be changed by this operation. Properties for which no input value is
provided remain unchanged by this operation.

Description
The request body object is validated against the data model for the Partition object type to ensure that the
request body contains only writable properties and the data types of those properties are as required. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

On successful execution, the value of each corresponding property of the object is updated with the value
provided by the input field, and status code 204 (No Content) is returned. When this operation changes
the value of any property for which property-change notifications are due, those notifications are emitted
asynchronously to this operation.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a partition object
for which the API user has object-access permission or if the URI in the request body does not designate
a resource of an expected type. If the API user does not have action/task permission to the Partition
Details operation, a 403 (Forbidden) status code is returned. If the status of the CPC hosting the partition
is not in a valid state, 409 (Conflict) status code is returned. A 409 (Conflict) status code is also returned if
the partition is in a transitional state ("starting" or "stopping") or if user sets boot-device to "iso-image",
but there is no ISO image mounted on the partition.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition
v Action/task permission to the Partition Details task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

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

Chapter 10. Dynamic Partition Manager (DPM) 183

 Level 04a

Table 86. Update Partition Properties: HTTP status and reason codes
HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
7 The data type of a field in the request body is not as expected.
15 access-diagnostic-sampling cannot be true when access-basic-sampling is
false.
18 A property that is only valid for type "ssc" was provided, but the type is not
"ssc". type "ssc" only allows "none" for boot-device.
118 There is an error in the fields related to the partition ID. One of:
v autogenerate-partition-id is false and the partition-id specified in the
request body is already in use.
v autogenerate-partition-id is false and partition-id is not included in the
request body.
v autogenerate-partition-id is true and partition-id is included in the
request body.
403 (Forbidden) 1 API user does not have the required permission for this operation
404 (Not Found) 1 The object ID in the URI {partition-id} does not designate an existing Partition
object, or the API user does not have object-access permission to it.
2 A URI in the request body does not designate a resource of an expected
type.

184 HMC Web Services API

 Level 04a

Table 86. Update Partition Properties: HTTP status and reason codes (continued)
HTTP error status Reason
code code Description
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation (must be in one of the following states: "active",
"service-required", "degraded", or "exceptions".)
8 The operation cannot be completed because it would result in inconsistencies
between the boot-device property and the related properties that identify the
specific boot device for that boot-device value. For example, if boot-device
is "storage-adapter", then boot-storage-device must contain a valid HBA
URI.

access-diagnostic-sampling cannot be set to true when access-basic-

sampling is false. access-basic-sampling cannot be set to false when
access-diagnostic-sampling is true.
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
110 Partition's processor-mode cannot be updated as the partition is a member
of a Capacity Group.
116 The reserve-resources value is true but resources are not available to be
reserved for this partition's use.
| 119 The value of the boot-storage-volume property does not designate a storage
| volume of type "boot" contained in a storage group that is attached to the
| partition.
|| 120 v Request contains boot-storage-volume property when the
| "dpm-storage-management" feature is disabled.
| v "storage-volume" is provided as value for boot-device property when the
| "dpm-storage-management" feature is disabled.
| v Request contains ipl-load-parameter when the "dpm-storage-
| management" feature is disabled.
|| 121 v Request contains boot-storage-device property when the
| "dpm-storage-management" feature is enabled.
| v "storage-adapter" is provided as a value for boot-device property when
| the "dpm-storage-management" feature is enabled.
| v Request contains boot-logical-unit-number when the "dpm-storage-
| management" feature is enabled.
| v Request contains boot-world-wide-port-name when the
| "dpm-storage-management" feature is enabled.
| 122 The storage-volume provided as value for boot-storage-volume property is
| "incomplete" or is not mapped to any LUN.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Chapter 10. Dynamic Partition Manager (DPM) 185

 Level 04a

Example HTTP interaction

POST /api/partitions/30d8fe00-89c3-11e5-9b53-020000000056 HTTP/1.1

x-api-session: 2b1cv9k5i0v3tfgm6uo5vggzzj3eoer6zeiu7jt79tznjeqanl
content-type: application/json
content-length: 90
{
"cp-processors":5,
"description":"Sample partition description",
"name":"Serv-sample"
}

Figure 36. Update Partition Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 13 Nov 2015 06:43:45 GMT

<No response body>

Figure 37. Update Partition Properties: Response

Usage note
This is a synchronous operation and as such does not complete until the partition has been updated.
Depending on the I/O configuration associated with the partition, this operation may take a considerable
amount of time to complete. API clients that are concerned about that should use the Update Partition
Properties Asynchronously operation instead.

Update Partition Properties Asynchronously

The Update Partition Properties Asynchronously operation updates one or more of the writable
properties of the Partition object designated by {partition-id} asynchronously.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/async-update

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Request body contents

The request body is expected to contain one or more field names representing writable partition
properties, along with the new values for those fields. The request body can and should omit fields for
properties whose values are not to be changed by this operation. Properties for which no input value is
provided remain unchanged by this operation.

Response body contents

Once the update request 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.

186 HMC Web Services API

 Level 04a

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” on page
188. The job-results field contains null when this operation is successful. When it is not 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.

Description
The request body object is validated against the data model for the Partition object type to ensure that the
request body contains only writable properties and the data types of those properties are as required. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

This operation asynchronously updates the designated partition. When the operation is initiated, a 202
(Accepted) status code is returned. The response body contains a URI that may be queried to retrieve the
status of the operation. See “Query Job Status” on page 80 for information on how to query job status.
When the operation has completed, an asynchronous result message is sent, with Job Status and Reason
Codes described in “Job status and reason codes” on page 188.

On successful execution of the asynchronous portion of this operation, the value of each corresponding
property of the object is updated with the value provided by the input field, and status code 204 (No
Content) is returned in the asynchronous result document. When this operation changes the value of any
property for which property-change notifications are due, those notifications are emitted asynchronously
to this operation.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a Partition object
for which the API user has object-access permission or if the URI in the request body does not designate
a resource of an expected type. If the API user does not have action/task permission to the Partition
Details operation, a 403 (Forbidden) status code is returned. If the status of the CPC hosting the partition
is not in a valid state, 409 (Conflict) status code is returned. A 409 (Conflict) status code is also returned if
the partition is in a transitional state ("starting" or "stopping").

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition
v Action/task permission to the Partition Details 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” on page 186.

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

Chapter 10. Dynamic Partition Manager (DPM) 187

 Level 04a

Table 87. Update Partition Properties Asynchronously: HTTP status and reason codes
HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden) 1 API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI {partition-id} does not designate an existing Partition
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 Partition status is not valid to perform the operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation (must be in one of the following states: "active",
"service-required", "degraded", or "exceptions".)
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Job status and reason codes

Table 88. Update Partition Properties Asynchronously: Job status and reason codes
HTTP error status Reason
code code Description
204 (No Content) N/A Update completed successfully.
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
7 The data type of a field in the request body is not as expected.
15 access-diagnostic-sampling cannot be true when access-basic-sampling is
false.
18 A property that is only valid for type "ssc" was provided, but the type is not
"ssc".

The partition type "ssc" only allows "none" for the boot-device.
118 There is an error in the fields related to the partition ID. One of:
v autogenerate-partition-id is false and partition-id specified in the request
body is already in use.
v autogenerate-partition-id is false and partition-id is not included in the
request body.
v autogenerate-partition-id is true and partition-id is included in the
request body.

188 HMC Web Services API

 Level 04a

Table 88. Update Partition Properties Asynchronously: Job status and reason codes (continued)
HTTP error status Reason
code code Description
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation (must be in one of the following states: "active",
"service-required", "degraded", or "exceptions".)
8 boot-device can only be set if the boot device type ("network-adapter",
"storage-adapter", "ftp", "iso-image", etc.) points to a valid
URI/Hostname/ISO image. Boot device type cannot be set to null if the boot
device points to the corresponding boot device type.

access-diagnostic-sampling cannot be set to true when access-basic-

sampling is false.

access-basic-sampling cannot be set to false when access-diagnostic-

sampling is true.
110 Partition's processor-mode cannot be updated as the partition is a member
of a Capacity Group.
116 The reserve-resources boolean is true but resources are not available to be
reserved for this partition’s use.
| 119 The value of the boot-storage-volume property does not designate a storage
| volume of type "boot" contained in a storage group that is attached to the
| partition.
|| 120 v Request contains boot-storage-volume property when the
| "dpm-storage-management" feature is disabled.
| v "storage-volume" is provided as value for boot-device property when the
| "dpm-storage-management" feature is disabled.
| v Request contains ipl-load-parameter when the "dpm-storage-
| management" feature is disabled.
|| 121 v Request contains boot-storage-device property when the
| "dpm-storage-management" feature is enabled.
| v "storage-adapter" is provided as a value for boot-device property when
| the "dpm-storage-management" feature is enabled.
| v Request contains boot-logical-unit-number when the "dpm-storage-
| management" feature is enabled.
| v Request contains boot-world-wide-port-name when the
| "dpm-storage-management" feature is enabled.
| 122 The storage-volume provided as value for boot-storage-volume property is
| "incomplete" or is not mapped to any LUN.
500 (Server Error) 100 Partition update failed.
101 Partition update job timed out.

Chapter 10. Dynamic Partition Manager (DPM) 189

 Level 04a

Example HTTP interaction

POST /api/partitions/279cee22-50d3-11e7-b285-fa163ef98b8b/operations/async-update HTTP/1.1

x-api-session: 1wb0irgy7jn2edj7ptyqy4twit24m0b7krskctnf7h5dr91goz
content-type: application/json
content-length: 20
{
"name":"Testname"
}

Figure 38. Update Partition Properties Asynchronously: Request

202 Accepted
server: Hardware management console API web server / 2.0
location: /api/jobs/df6b825a-55b2-11e7-8f25-fa163e6e13bb
cache-control: no-cache
date: Tue, 20 Jun 2017 12:20:39 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/df6b825a-55b2-11e7-8f25-fa163e6e13bb"
}

Figure 39. Update Partition Properties Asynchronously: Response

Start Partition
The Start Partition operation allocates the physical resources required by the partition and begins its
execution on the CPC by booting the partition as configured by its boot-related properties.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/start

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Response body contents

Once the start request 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 start status updates.

Asynchronous result description

Once the start 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 from the Start Partition request.

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” on page 192. The job-results field contains an empty JSON
object when this operation is successful. When it is not successful, the job-results field contains an object
with the following field:

190 HMC Web Services API

 Level 04a

Field name Type Description

message String The message text describing the detailed error that occurred when the
operation was not successful.

Description
This operation asynchronously starts the identified partition. When the operation is initiated, a 202
(Accepted) status code is returned. The response body includes a URI that may be queried to retrieve the
status of the operation. See “Query Job Status” on page 80 for information on how to query job status.
When the operation has completed, an asynchronous result message is sent, with Job Status and Reason
Codes described in “Job status and reason codes” on page 192.

If the Partition object's boot-device property is "none", then no program is started in the new partition.
However, other portions of the operation are performed and the partition is placed in the "paused" state.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a partition object
for which the API user has object-access permission. If the user does not have action/task permission to
the Start Partition action, a 403 (Forbidden) status code is returned. If the status of the partition is not
valid, 409 (Conflict) status code is returned. The valid states of the partition are "stopped", "paused" and
"terminated". A 409 (Conflict) status code is also returned if the CPC hosting the partition is not in a
valid state, or if the CPC does not have sufficient processors, memory or adapter resources to allocate to
the partition.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition
v Action/task permission for the Start Partition 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” on page 190.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
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 ({partition-id}) does not designate an existing
Partition object, or the API user does not have object-access permission to
the object.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

Chapter 10. Dynamic Partition Manager (DPM) 191

 Level 04a

Job status and reason codes

Table 89. Start Partition: Job status and reason codes
HTTP error status Reason
code code Description
200 (OK) N/A Start operation completed successfully.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation (must be one of the following states: "active", "service-required",
"degraded" and "exceptions".)
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
110 There is no DHCP info or an error occurred when trying to resolve DHCP
information.
111 DHCP file error occurred.
112 DNS lookup error has occurred.
113 An error has occurred during network boot component/server/configuration
download.
114 An error occurred when parsing network boot configuration, or when
executing network boot program.
114 An error occurred during removable media load.
115 An error occurred during FTP load.
116 The CPC does not have sufficient processor, memory, or adapter resources to
allocate to the partition to perform start operation.
117 An error occurred during initialization on the network boot device or there
was an error in internal setup during network boot.
118 The count of the partitions in active state has reached its maximum.
119 The specified device does not contain a bootable dump program.
119 DHCP lease failed on device or there was a DHCP lease internal error.
120 The partition configuration is not valid for a Secure Service Container
partition. The specific error reason is returned as additional error text.
Possible error conditions are:
v Secure Service Container Management NIC is missing (there needs to be
at least one Secure Service Container Management NIC).
v At least one NIC was configured in static IPv4 mode, but no
ssc-ipv4-gateway was provided.
| 122 The operation cannot be performed because the boot-storage-volume
| property does not designate a storage volume that is fulfilled.
500 (Server Error) 100 Partition start failed.
101 Partition start job timed out.
263 Operation failed.

192 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/operations/start HTTP/1.1

x-api-session: pd0nrulei0qsa1mwlpaw7cmq26rnsdcdhtp4w4m9gzse7gybg
content-type: application/json

Figure 40. Start Partition: Request

202 Accepted
server: zSeries management console API web server / 2.0
location: /api/jobs/913b0490-d537-11e5-a9b8-5ef3fcb21ee8
cache-control: no-cache
date: Wed, 17 Feb 2016 05:30:34 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/913b0490-d537-11e5-a9b8-5ef3fcb21ee8"
}

Figure 41. Start Partition: Response

Stop Partition
The Stop Partition operation stops the Partition object designated by {partition-id}.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/stop

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Response body contents

Once the stop request 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.

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” on page 195. The job-results field contains an empty JSON
object when this operation is successful. When it is not 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.

Chapter 10. Dynamic Partition Manager (DPM) 193

 Level 04a

Description
Stop Partition is an orderly process for terminating a partition.

Stopping a partition includes:

v Stopping the execution of (logical) processors associated with the partition.
v Unloading the partition's operating system.
v Freeing non-reserved CPC processor, memory, and adapter resources so that those resources are
available for use by other partitions.

After the partition is stopped, the partition is no longer operational.

The operation asynchronously stops the identified partition. When the operation is initiated, a 202
(Accepted) status code is returned. The response body includes a URI that may be queried to retrieve the
status of the operation. See “Query Job Status” on page 80 for information on how to query job status.
When the operation has completed, an asynchronous result message is sent, as described in “Job status
and reason codes” on page 195.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a partition object
for which the API user has object-access permission. If the user does not have action/task permission to
the Stop Partition action, a 403 (Forbidden) status code is returned. If the partition is not in a valid state
to perform the stop operation, 409 (Conflict) status code is returned. The valid states to perform Stop
Partition are "active", "paused", and "terminated" .

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition.
v Action/task permission for the Stop Partition 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” on page 193.

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 Reason

code code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
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 ({partition-id}) does not designate an existing
Partition object, or the API user does not have object-access permission to
the object.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35.

194 HMC Web Services API

 Level 04a

Job status and reason codes

Table 90. Stop Partition: Job status and reason codes
HTTP error status Reason
code code Description
200 (OK) N/A Stop completed successfully.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "active",
"paused", or "terminated") .
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
6 The state of the CPC hosting the partition is not valid to perform the
operation (must be in one of the following states: "active",
"service-required", "degraded", or "exceptions".)
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
500 (Server Error) 100 Partition stop failed.
101 Partition stop job timed out.
263 Operation failed.

Example HTTP interaction

POST /api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/operations/stop HTTP/1.1

x-api-session: 44p85d6k4nve3pdaglbdxyohewkhj6hwvnqo9jv0czp226h82p
content-type: application/json

Figure 42. Stop Partition: Request

202 Accepted
server: zSeries management console API web server / 2.0
location: /api/jobs/eebbef94-d537-11e5-9e2e-5ef3fcb21ee8
cache-control: no-cache
date: Wed, 17 Feb 2016 05:33:10 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/eebbef94-d537-11e5-9e2e-5ef3fcb21ee8"
}

Figure 43. Stop Partition: Response

Dump Partition
| The Dump Partition operation loads a standalone dump program from a designated SCSI device. This
| operation is not supported when the "dpm-storage-management" feature is enabled on the target
| Partition object.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/scsi-dump

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Chapter 10. Dynamic Partition Manager (DPM) 195

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

dump-load-hba-uri String/ Required The URI of the HBA associated with the partition that provides
URI access to the storage-area network containing the SCSI device from
which the dump program is loaded.
dump-world-wide- String (16) Required The worldwide port name (WWPN) of the target storage controller
port-name that contains the SCSI device from which the dump program is
loaded, in hexadecimal.
dump-logical-unit- String Required The hexadecimal logical unit number (LUN) that identifies the SCSI
number (1-16) device from which the dump program is loaded.